Takuto CLI reference

The Takuto CLI is the companion tool for Takuto Core: it generates your config files, orchestrates Docker Compose, and runs the authentication flows. It is MIT-licensed and wraps the same engine you’d otherwise run by hand.

Installation

Homebrew (macOS / Linux — recommended):

brew install takuto-team/tap/takuto

Manual binary download. Grab the binary for your platform from the Releases page:

# macOS (Apple Silicon)
curl -L -o takuto https://github.com/takuto-team/takuto-cli/releases/latest/download/takuto-darwin-arm64
chmod +x takuto && sudo mv takuto /usr/local/bin/

# macOS (Intel) — takuto-darwin-amd64
# Linux (amd64)  — takuto-linux-amd64
# Linux (arm64)  — takuto-linux-arm64

On Windows, download takuto-windows-amd64.exe and add it to your PATH.

The CLI needs Docker or Podman installed — it auto-detects which one you have, including aliases.

Commands

The CLI has five subcommands.

takuto setup

Runs the interactive setup wizard. Most configuration now lives in the dashboard, so the wizard is short — it only asks for the dashboard port and, if you use an external database (Postgres / MySQL / MariaDB), its connection details (otherwise it defaults to the built-in SQLite). It generates takuto.yml plus a .takuto/ directory with config.toml, takuto.env, and a workflows/ folder containing the three starter workflow definitions. The files are created in the current directory — it does not need to be a project folder, and running setup in different directories keeps isolated Takuto instances side by side.

takuto setup

my-project/
  takuto.yml                  # Docker Compose orchestration
  .takuto/
    config.toml                # project configuration
    takuto.env                # secrets and API tokens
    workflows/                 # pipeline step definitions
      implement_ticket.toml
      merge_base.toml
      address_pr_comments.toml

takuto auth

Optional — not recommended. Runs interactive OAuth login flows inside the container:

1. GitHub CLI (gh) — for pushing branches and creating PRs.
2. Your AI provider — Claude Code, Cursor Agent, Codex, or OpenCode (self-hosted).
3. Repository clone — clones your project into the container’s workspace.

OAuth grants broad account access, so the recommended path is scoped API keys/tokens instead: set your provider’s credentials (e.g. ANTHROPIC_API_KEY, CURSOR_API_KEY, OPENAI_API_KEY) and a scoped GH_TOKEN in .takuto/takuto.env, or enter them from the dashboard — see Configuration for the full list. Use takuto auth only if you specifically need the interactive login flow.

takuto start

Starts the Takuto Core services and the dashboard.

takuto start

Open http://localhost:8080. On first boot, create the initial admin account. If Jira or GitHub Issues are configured, polling starts automatically; otherwise click + to start a workflow manually.

takuto stop

takuto stop

Stops the Takuto services (a docker compose down). Auth state, workflow snapshots, and caches persist in named Docker volumes.

takuto restart

takuto restart

Restarts the services. Paused or in-progress workflows resume from saved state.

Multi-project isolation

Docker Compose prefixes every volume with the directory name (e.g. my-app_claude-auth, my-app_workspace). To run Takuto on several projects at once, use a separate directory per project — each gets fully isolated auth, workspace, and caches with no extra configuration.

Example presets

The Takuto repository ships self-contained presets you can copy instead of running the wizard from scratch:

Each preset includes a tuned install command, run commands wired to the dashboard, and sensible mise/port defaults. Copy the folder, edit config.toml (the values marked ← — repo URL, branch, ticketing system), and start as usual:

cp -r examples/react-vite/ my-project && cd my-project
# edit .takuto/config.toml
docker compose -f takuto.yml run --rm -it takuto setup
docker compose -f takuto.yml up -d

Preset notes:

• react-vite — npm ci install; dynamic port forwarding for Vite (5173) and Storybook (6006).
• ruby-rails — bundle install; Ruby 3.3 auto-installed via mise on first editor open (or your .ruby-version / .tool-versions if present); the Rails server binds to 0.0.0.0 so port forwarding works. Add your database host to [network] extra_egress_hosts.
• rust — cargo build; the Rust toolchain is already baked into the image.

Manual setup (without the CLI)

If you’d rather not use the CLI, copy a preset and run Compose directly — see the Manual Setup section in the Takuto README, or the Install Takuto Core page to run the engine from source.