Takuto CLI 参考

Takuto CLI 是 Takuto Core 的配套工具：它替你生成配置文件、编排 Docker Compose 并跑认证流程。它采用 MIT 许可，封装的正是你本来要手动运行的那个引擎。

安装

Homebrew（macOS / Linux —— 推荐）：

brew install takuto-team/tap/takuto

手动下载二进制文件。 从 Releases 页面取得适合你平台的二进制：

# 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

在 Windows 上，下载 takuto-windows-amd64.exe 并把它加入你的 PATH。

CLI 需要装好 Docker 或 Podman —— 它会自动识别你装的是哪一个，包括别名。

命令

CLI 有五个子命令。

`takuto setup`

运行交互式 setup 向导。如今大部分配置都已落在仪表盘里，所以这个向导很短 —— 它只会询问 仪表盘端口，以及，如果你使用外部数据库（Postgres / MySQL / MariaDB），它的连接信息 （否则默认使用内置的 SQLite）。它会生成 takuto.yml，外加一个含 config.toml、 takuto.env 和一个 workflows/ 文件夹（内含三个起步 workflow 定义）的 .takuto/ 目录。这些文件创建在当前目录 —— 它不一定得是某个项目文件夹，在不同的目录里运行 setup 就能让相互隔离的 Takuto 实例并存。

takuto setup

my-project/
  takuto.yml                  # Docker Compose 编排
  .takuto/
    config.toml                # 项目配置
    takuto.env                # 密钥和 API token
    workflows/                 # 流水线步骤定义
      implement_ticket.toml
      merge_base.toml
      address_pr_comments.toml

`takuto auth`

可选 —— 不推荐。 在 container 内部运行交互式的 OAuth 登录流程：

GitHub CLI（gh）—— 用于推送分支和创建 PR。
你的 AI 提供商 —— Claude Code、Cursor Agent、Codex 或 OpenCode（自托管）。
克隆仓库 —— 把你的项目克隆进 container 的 workspace。

OAuth 会授予宽泛的账号访问权限，因此推荐的路径是改用限定范围的 API key / token：在 .takuto/takuto.env 中设置好你提供商的凭据（例如 ANTHROPIC_API_KEY、CURSOR_API_KEY、 OPENAI_API_KEY）以及一个限定范围的 GH_TOKEN，或从仪表盘填入它们 —— 完整清单见配置。只有在你确实需要交互式登录流程时，才使用 takuto auth。

`takuto start`

启动 Takuto Core 服务和仪表盘。

takuto start

打开 http://localhost:8080。首次启动时，创建初始的 admin 账号。如果配置了 Jira 或 GitHub Issues，轮询会自动开始；否则点击 + 手动启动一个 workflow。

`takuto stop`

takuto stop

停止 Takuto 服务（一次 docker compose down）。认证状态、workflow 快照和缓存会在命名的 Docker 卷里持久保留。

`takuto restart`

takuto restart

重启服务。暂停的或进行中的 workflow 会从保存的状态恢复。

多项目隔离

Docker Compose 会用目录名给每个卷加前缀（例如 my-app_claude-auth、my-app_workspace）。要同时在多个项目上运行 Takuto，请为每个项目用一个单独的目录 —— 每个都拥有完全隔离的认证、workspace 和缓存，无需任何额外配置。

示例预设

Takuto 仓库附带了一些自包含的预设，你可以直接复制，而不必从头运行向导：

预设	技术栈	run command
`react-vite`	React + Vite	Dev Server、Storybook、Preview Build
`ruby-rails`	Ruby on Rails	Rails Server、Console、Sidekiq
`rust`	Rust	Run Server、`cargo watch` 测试

每个预设都包含一条调好的安装命令、接到仪表盘的 run command，以及合理的 mise/端口默认值。复制文件夹，编辑 config.toml（标有 ← 的值 —— 仓库 URL、分支、工单系统），然后照常启动：

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

预设说明：

react-vite —— npm ci 安装；为 Vite（5173）和 Storybook（6006）做动态端口转发。
ruby-rails —— bundle install；首次打开编辑器时通过 mise 自动安装 Ruby 3.3 （或使用你的 .ruby-version / .tool-versions，如果存在）；Rails 服务器绑定到 0.0.0.0，以便端口转发生效。把你的数据库主机加进 [network] extra_egress_hosts。
rust —— cargo build；Rust 工具链已经内置在镜像里。

手动设置（不用 CLI）

如果你宁可不用 CLI，可复制一个预设并直接运行 Compose —— 参见 Takuto README 中的手动设置一节，或参见安装 Takuto Core 页面以从源码运行引擎。