--- title: CLI Reference description: "Look up Tako command groups, global options, environment selection, and structured output for local development, deployment, and operations." --- ## Search Page index: https://tako.sh/llms.txt. Docs and blog posts also have .md URLs. This site has a search endpoint: https://context7.com/api/v2/ask?siteKey=ask_b8918f0414955bb91bfa1a89&query=. It returns documentation that answers the question, with a source link for each part. No API key is needed. If nothing matches, it says so. ```bash tako [--version] [-v|--verbose] [--ci] [--json] [--dry-run] [-c|--config ] [--ssh-passphrase ] ``` Progress, prompts, and diagnostics normally go to stderr. Command results and machine-readable data go to stdout. Interactive `tako dev` owns stdout for its live interface and logs; `tako run` preserves child stdout. Use `tako --help` or the connected MCP tool's schema for the exact arguments supported by your installed CLI. This reference explains command groups and behavior; task pages cover complete workflows. ## Global Options | Option | Meaning | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `--version` | Print the CLI version and exit. | | `-v`, `--verbose` | Append-only transcript with timestamps, log levels, and debug diagnostics. | | `--ci` | Deterministic non-interactive output: no colors, spinners, raw mode, or prompts. | | `--json` | Emit structured JSON on stdout. Progress, diagnostics, and errors stay on stderr. | | `--dry-run` | Show side effects without performing them. Supported by deploy, servers add/remove, delete, and side-effecting backup commands. | | `-c`, `--config ` | Use an explicit config file. `.toml` is appended when omitted. | | `--ssh-passphrase ` | Use a passphrase for encrypted local SSH keys. | App-scoped commands that honor `-c`: `agents`, `mcp`, `init`, `dev`, `run`, `logs`, `deploy`, `releases`, `backups`, `delete`, `secrets`, `credentials`, `storages`, `generate`, and project-context `scale`. For finite commands, `--json` prints one final object. Commands without a specialized schema use `{"ok":true,"command":""}`. Failures print `{"ok":false,"error":{"message":"..."}}` on stdout and the human-readable error on stderr. Specialized objects: `status` includes `servers`; `doctor` includes paths, CA, dev server, apps, and proxy checks; `servers list`, `secrets list`, `credentials list`, `dev list`, `backups list`/`status`, and `releases list` include their collections. Streaming exceptions keep stdout as JSONL until interrupted: `tako logs --tail --json` emits one log record per line, and `tako dev --json` emits a ready object, then log and event records, with no logo or TUI. `tako run` is also an exception: child stdout stays untouched and no JSON result object is appended. Installed CLIs send an anonymous event per command so we can count unique users and see which commands run. Set `TAKO_TELEMETRY=0` to opt out. See [Usage stats](#usage-stats). ## Project Setup ```bash tako init ``` Creates `tako.toml`, updates `.gitignore`, detects runtime and preset, asks for app name and production route, and installs the SDK package for JS and Go projects. If the production route is a wildcard route, init can collect and encrypt the Cloudflare credential required for Let's Encrypt DNS-01. Interactive init then offers coding agent setup with a default of yes; non-interactive init leaves agent settings alone. ```bash tako generate tako gen tako g ``` Refreshes generated project files: - JS/TS: `tako.d.ts` with environment names, secret names, storage bindings, channel metadata, typed Store params and data, workflow metadata, and env var names. - Go: `tako_secrets.go` with typed secret accessors. For JS/TS, generation keeps an existing `tako.d.ts` in `app/`, `src/`, or the project root. Empty existing `channels/` or `workflows/` directories get demo definitions. ## `tako agents` ```bash tako agents tako agents --agent codex,claude-code --yes tako agents --agent cursor --dry-run --json ``` Installs bundled workflow and SDK skills and configures the local MCP server for Codex, Claude Code, Cursor, and VS Code Copilot. Detects clients by default; `--agent` selects them explicitly (repeatable or comma-separated). `--yes` skips the setup confirmation. `--dry-run` previews files without writing. All settings are project-local; existing unrelated configuration is preserved. Re-run to refresh after upgrading Tako. See [Coding agents](/docs/agents/). ## `tako mcp` ```bash tako mcp tako mcp -c /path/to/project/tako.toml ``` Serves Tako tools, bundled docs, and SDK skills over MCP stdio. Designed to be started by a coding agent; stdout is reserved for MCP protocol messages, including with `--json`. Tools use existing CLI credentials and permissions. See [Coding agents](/docs/agents/) for manual client configuration and tool behavior. ## `tako dev` ```bash tako dev tako dev vite dev tako dev --variant preview tako dev --var preview tako dev --tunnel tako dev --restart tako dev --background --json ``` Starts or attaches to a local dev session behind trusted HTTPS and real hostnames. `--variant foo` uses a variant hostname such as `myapp-foo.test`; `--restart` restarts the process with the current config instead of attaching. It starts the dev daemon, prepares DNS/proxy/CA setup, generates files, injects secrets and storage through fd 3, waits for fd-4 readiness, and registers routes. Pass a command after `tako dev` to override the configured dev command for that run: ```bash tako dev vite dev tako dev npm run dev tako dev -- vite dev ``` Use `--` when the child command conflicts with a Tako subcommand such as `stop` or `list`, or when the child command starts with a flag. Interactive controls: | Key | Action | | -------- | ------------------------------------------------------------------ | | `l` | Toggle LAN mode for managed local routes. | | `t` | Toggle a temporary public tunnel URL. | | `r` | Restart the app. | | `b` | Leave the app running in the background and exit the attached CLI. | | `Ctrl+c` | Stop the app and exit. | The interactive status panel always shows local routes plus LAN and tunnel state. LAN and tunnel rows include their own enable/disable hints on the same rows; tunnel also shows starting and reconnecting states while it connects. Tunnel hostnames use `{app}-{id}.tako.website`; the id is derived from the app name and Tako Identity, so the same app gets the same URL when the same identity is available. If the tunnel connection drops, Tako keeps the URL reserved and reconnects automatically. One Tako Identity can have up to five active tunnel URLs connected at the same time; starting a sixth closes the oldest active tunnel for that identity. When a tunnel turns off, `tako dev` prints a log line with the close reason. Inactive tunnel URLs show a Tako error page in browsers and machine-readable errors for API clients. Subcommands: ```bash tako dev stop [name] tako dev stop --all tako dev list tako dev ls ``` `stop` without a name stops the app for the selected config file. `--all` stops all registered dev apps. `list` shows currently registered dev apps and any active tunnel URLs. `--background` exits after registration and readiness while the dev daemon keeps the app running. Combine it with `--json` for one ready object, then inspect with `tako dev list` and stop with `tako dev stop`. Global `--json` skips the interactive UI. `tako dev --json` prints a ready object with `app`, `url`, and `hosts`, then JSONL `log` and `event` records. `tako dev list --json` prints one object with an `apps` array. ## `tako doctor` ```bash tako doctor ``` Prints local diagnostics for the dev daemon, local DNS, TLS files, and platform-specific proxy setup. Global `--json` emits one object with `paths`, `ca`, `dev_server`, `apps`, and platform `proxy` checks instead of the human report. ## `tako run` ```bash tako run scripts/foo.ts tako run jobs/foo.go --dry tako run --eval 'console.log(tako.env)' -- --dry tako run --env staging scripts/foo.ts tako run -- cargo run --bin migrate ``` Runs a one-off command locally from the app directory with Tako project context. `--env` defaults to `development`. Script files are expanded by the selected runtime. Bun runs JS/TS scripts with Bun, Node runs TS scripts with type stripping, and Go runs `.go` files with `go run`. `--eval` runs inline source when the runtime supports it; JS runtimes support inline TypeScript. Use `-- {command...}` for exact commands and runtimes without a bare script rule. The child process receives `[vars]` plus `[vars.]`, `ENV`, `TAKO_BUILD=local`, `TAKO_DATA_DIR`, runtime defaults, and `TAKO_APP_ROOT` for JS apps. Tako decrypts local app secrets for the selected environment and passes the normal bootstrap envelope through `TAKO_BOOTSTRAP_DATA`. SDK-aware scripts use the same app SDK surfaces; JS/TS scripts can import `tako` and use `tako.secrets` and `tako.storages`. Secrets are not process env vars. `tako run` is local-only in v0; it does not run commands on deployed servers. ## Deploy And Runtime Operations ```bash tako deploy [--env ] [-y|--yes] [--force] [--description ] ``` Builds locally, uploads artifacts over signed HTTP management, prepares every mapped server, runs the optional release command on the leader, rolls instances, finalizes the release, and runs post-deploy backups when enabled. `--env` defaults to `production`. `development` is reserved for `tako dev`. Deploy requires the CLI, server, and release artifact to use the same protocol version; a mismatch fails before release commands, workflows, or app processes start. `--force` attempts the deploy despite a mismatch but does not skip normal validation or readiness checks. It is separate from `--yes`, which only skips confirmation. ```bash tako logs [--env ] [--tail] [--days N] ``` Shows app logs from all servers mapped to the environment. History defaults to three days. `--tail` streams. Global `--json` emits a final object with a `logs` array in history mode; with `--tail`, it emits JSONL records. ```bash tako scale [--service ] [--env ] [--server ] [--app ] tako scale --reset [--service ] [--env ] [--server ] [--app ] ``` Changes desired instance count on targeted servers. From a project, app identity is resolved from the config. Outside a project, pass `--app`, either as a base app with `--env` or as a full `{app}/{env}` deployment id. For Compose, the target defaults to `[compose].service`; `--service` selects another service. The count is a persistent override that survives deploys, rollbacks, and restarts. `--reset` clears the selected service override and applies its current Compose `deploy.replicas` default (one when omitted). Supply either a count or `--reset`. These flags require a Compose app. See [Compose scaling](/docs/docker-compose/#scale-individual-services) for limits and shared-volume behavior. ```bash tako delete [--env ] [--server ] [-y|--yes] tako rm ... tako remove ... tako undeploy ... tako destroy ... ``` Deletes one deployment target, drains and stops the app, removes runtime state, and removes the server-side app data tree for that app/environment on the selected server. ## Releases ```bash tako releases list [--env ] tako releases ls [--env ] tako releases rollback [--env ] [-y|--yes] ``` Release descriptions default to the commit subject for clean checkouts, `Uncommitted changes based on: ` for dirty checkouts, or `Local source snapshot` without Git history. Set `tako deploy --description "Fix reconnect handling"` to override the description. The dirty status remains visible with a custom description. `releases list --json` includes `description`, `commit_message`, and `git_dirty` for each release. Lists release/build history or rolls an environment back to a previous release. Rollback uses the standard rolling-update flow and reports partial server failures individually. ## Servers ```bash tako servers add [host|admin@host] [--name ] [--description ] [--port ] [--ssh-key ] [--vpn tailscale|netbird] [--http-port ] [--https-port ] [--install] tako servers list tako servers ls tako status tako servers reload [--force] tako servers upgrade [name] [--force] tako servers remove [name] tako servers rm [name] tako servers uninstall [name] [-y|--yes] ``` `servers add` writes global `config.toml`, checks the management endpoint and `tako@host` SSH access, enrolls signed management access, and records target metadata. If the server is running but inaccessible, interactive setup offers to repair access; if its state is unknown, it offers to install or repair it. After confirmation, Tako asks for an administrator with `root` pre-filled. Use `--install` to skip the confirmation, or pass `admin@host` to select the administrator without a prompt. Public HTTP and HTTPS ports default to `80` and `443`; override them with `--http-port` and `--https-port`. `--ssh-key` pins a specific private key for the server; connections then use only that key instead of trying `~/.ssh` defaults and `ssh-agent`. The interactive wizard prompts for the key, prefilled with your default `~/.ssh` key. `servers add` asks which VPN to use unless a provider is supplied or saved for that host. Connected providers appear first with a `detected` hint and the first is preselected. Use `--vpn tailscale` or `--vpn netbird` for scripts. Both machines must already be connected to the selected VPN. The provider is saved per server; existing entries default to Tailscale. `status` prints a deployment snapshot grouped by server, with compact server summary, routes, and app rows. `servers reload` performs a zero-downtime service reload by default. Its `--force` flag performs a full restart. `servers upgrade` checks the candidate protocol against the CLI and every active app before reload, checks again after readiness, and restores and restarts the previous binary if the upgrade fails. `servers upgrade --force` attempts an incompatible upgrade but keeps readiness and rollback checks enabled. `servers uninstall` removes the remote service, binaries, data, sockets, and local server entry. ## Secrets ```bash tako secrets set [--env ] [--expires-on ] [--sync] tako secrets add ... tako secrets rm [--env ] [--sync] tako secrets list tako secrets sync [--env ] tako secrets key export [--env ] tako secrets key import [--env ] [--passphrase] ``` Secrets are app-facing values delivered to SDKs. Values are encrypted in `.tako/secrets.json`; keys are stored outside the project. Interactive prompts accept pasted multiline values and ask before trimming surrounding whitespace; non-interactive commands read the full stdin stream. `--sync` sends updates to deployed servers and rolls fresh processes so they receive the new bootstrap envelope. If any secret in an environment fails to decrypt, that environment is not synced — a partial push would remove the failed secret from the server. Expiry accepts `YYYY-MM-DD` or `in N days`. Leave it blank for no expiry. Deploy fails on expired selected-environment secrets and warns when they expire within 30 days. ## Provider Credentials ```bash tako credentials set [name] [--env ] [--expires-on ] tako creds set ... tako credentials rm [--env ] tako credentials list ``` Running `tako credentials` without a subcommand lists credentials. Set and remove prompt for an environment when `--env` is omitted; non-interactive use requires `--env`. Provider credentials are Tako-owned runtime credentials, not app secrets. Supported names are `ssl.cloudflare` and `postgres_url`. They are encrypted in `.tako/secrets.json`, never exposed to app code, and not synced by `tako secrets sync`. `ssl.cloudflare` powers Let's Encrypt DNS-01 and Cloudflare Origin CA. `postgres_url` enables shared channel replay, Presence membership, Store invalidation, and workflow state for multi-server deployments. It is a provider credential and is not exposed to app code. ## Storage ```bash tako storages add [--env ] [--resource ] [--provider s3|local] [--bucket ] [--endpoint ] [--region ] [--access-key-id ] [--secret-access-key ] [--expires-on ] [--force-path-style] [--public-base-url ] tako storages credentials [--env ] [--access-key-id ] [--secret-access-key ] [--expires-on ] ``` Storage commands default to `--env production` and `--provider s3`. `storages add` writes the app binding to `tako.toml`. For S3 resources it also writes resource metadata and encrypted credentials. `storages credentials` rotates credentials for an existing top-level S3 resource without adding an app binding, which is useful for backup-only resources. ## Backups ```bash tako backups now [--env ] [--server ] tako backups list [--env ] [--server ] tako backups ls [--env ] [--server ] tako backups status [--env ] tako backups download [--env ] [--server ] [--output ] tako backups restore [--env ] [--server ] [-y|--yes] ``` Backup commands default to `production`, require project context, and target the deployment id `{app}/{env}` over signed HTTP management. Multi-server download and restore require `--server`. ## Local CLI Maintenance ```bash tako completions [-y|--yes] tako upgrade tako uninstall [-y|--yes] tako version ``` `completions` installs bash, zsh, and fish completion scripts for shells that are on `PATH`. zsh is installed only when a writable directory is already on `fpath`; otherwise Tako prints how to add one. `upgrade` updates the local CLI install. On macOS, official CLI upgrades support Apple Silicon and Intel. Intel builds publish separately after each release. If an Intel download is temporarily unavailable, retry once that build finishes. `uninstall` removes local Tako binaries, local data, completion scripts, and platform-specific dev services/config after confirmation. ## Usage stats Official CLI installs send one anonymous event per command so we can count unique users and see which commands run (`deploy`, `dev`, `init`, and so on). The event includes CLI version, OS, architecture, and the command name. It does not include app names, paths, server hosts, environment names, or command arguments. `tako-server` does not send usage stats. Opt out: ```bash export TAKO_TELEMETRY=0 ``` Usage stats are always off in CI (`CI=true` or `--ci`), even with `TAKO_TELEMETRY=1`. Local Cargo builds are off by default; set `TAKO_TELEMETRY=1` to send from local builds outside CI.