CLI Reference
Complete command reference for the AACWorkflow CLI and agent daemon.
The aacworkflow CLI connects your local machine to AACWorkflow. It handles authentication, workspace management, issue tracking, and runs the agent daemon that executes AI tasks locally.
Authentication
Browser Login
aacworkflow loginOpens your browser for OAuth authentication, creates a 90-day personal access token, and auto-configures your workspaces.
Token Login
aacworkflow login --token <mul_...>Authenticate using a personal access token directly. Useful for headless environments. Pass --token= with an empty value to be prompted interactively (so the token never lands in shell history).
Check Status
aacworkflow auth statusShows your current server, user, and token validity.
Logout
aacworkflow auth logoutRemoves the stored authentication token.
Agent Daemon
The daemon is the local agent runtime. It detects available AI CLIs on your machine, registers them with the AACWorkflow server, and executes tasks when agents are assigned work.
Start
aacworkflow daemon startBy default, the daemon runs in the background and logs to ~/.aacworkflow/daemon.log.
To run in the foreground (useful for debugging):
aacworkflow daemon start --foregroundStop
aacworkflow daemon stopStatus
aacworkflow daemon status
aacworkflow daemon status --output jsonShows PID, uptime, detected agents, and watched workspaces.
Logs
aacworkflow daemon logs # Last 50 lines
aacworkflow daemon logs -f # Follow (tail -f)
aacworkflow daemon logs -n 100 # Last 100 linesSupported Agents
The daemon auto-detects these AI CLIs on your PATH:
| CLI | Command | Description |
|---|---|---|
| Antigravity | agy | Google's coding agent |
| Claude Code | claude | Anthropic's coding agent |
| CodeBuddy | codebuddy | Tencent's coding agent |
| Codex | codex | OpenAI's coding agent |
| Copilot | copilot | GitHub's coding agent |
| Cursor Agent | cursor-agent | Cursor coding agent |
| Hermes | hermes | Nous Research coding agent |
| Kimi | kimi | Moonshot coding agent |
| Kiro CLI | kiro-cli | Kiro ACP coding agent |
| OpenCode | opencode | Commercial coding agent |
| OpenClaw | openclaw | Commercial coding agent |
| Pi | pi | Inflection coding agent |
| Qoder | qodercli | Alibaba's coding agent |
| Trae | traecli | ByteDance's coding agent |
You need at least one installed. The daemon registers each detected CLI as an available runtime.
How It Works
- On start, the daemon detects installed agent CLIs and registers a runtime for each agent in each watched workspace
- It polls the server at a configurable interval (default: 30s) for claimed tasks
- When a task arrives, it creates an isolated workspace directory, spawns the agent CLI, and streams results back
- Heartbeats are sent periodically (default: 15s) so the server knows the daemon is alive
- On shutdown, all runtimes are deregistered
Configuration
Daemon behavior is configured via flags or environment variables:
| Setting | Flag | Env Variable | Default |
|---|---|---|---|
| Poll interval | --poll-interval | AACWORKFLOW_DAEMON_POLL_INTERVAL | 30s |
| Heartbeat interval | --heartbeat-interval | AACWORKFLOW_DAEMON_HEARTBEAT_INTERVAL | 15s |
| Agent timeout | --agent-timeout | AACWORKFLOW_AGENT_TIMEOUT | 2h |
| Max concurrent tasks | --max-concurrent-tasks | AACWORKFLOW_DAEMON_MAX_CONCURRENT_TASKS | 20 |
| Daemon ID | --daemon-id | AACWORKFLOW_DAEMON_ID | hostname |
| Device name | --device-name | AACWORKFLOW_DAEMON_DEVICE_NAME | hostname |
| Runtime name | --runtime-name | AACWORKFLOW_AGENT_RUNTIME_NAME | Local Agent |
| Workspaces root | — | AACWORKFLOW_WORKSPACES_ROOT | ~/aacworkflow_workspaces |
Agent-specific overrides:
| Variable | Description |
|---|---|
AACWORKFLOW_CLAUDE_PATH | Custom path to the claude binary |
AACWORKFLOW_CLAUDE_MODEL | Override the Claude model used |
AACWORKFLOW_CODEX_PATH | Custom path to the codex binary |
AACWORKFLOW_CODEX_MODEL | Override the Codex model used |
AACWORKFLOW_OPENCODE_PATH | Custom path to the opencode binary |
AACWORKFLOW_OPENCODE_MODEL | Override the OpenCode model used |
AACWORKFLOW_OPENCLAW_PATH | Custom path to the openclaw binary |
AACWORKFLOW_OPENCLAW_MODEL | Override the OpenClaw model used |
AACWORKFLOW_HERMES_PATH | Custom path to the hermes binary |
AACWORKFLOW_HERMES_MODEL | Override the Hermes model used |
AACWORKFLOW_PI_PATH | Custom path to the pi binary |
AACWORKFLOW_PI_MODEL | Override the Pi model used |
AACWORKFLOW_CURSOR_PATH | Custom path to the cursor-agent binary |
AACWORKFLOW_CURSOR_MODEL | Override the Cursor model used |
AACWORKFLOW_KIMI_PATH | Custom path to the kimi binary |
AACWORKFLOW_KIMI_MODEL | Override the Kimi model used |
AACWORKFLOW_KIRO_PATH | Custom path to the kiro-cli binary |
AACWORKFLOW_KIRO_MODEL | Override the Kiro model used |
AACWORKFLOW_COPILOT_PATH | Custom path to the copilot binary |
AACWORKFLOW_COPILOT_MODEL | Override the Copilot model used |
AACWORKFLOW_CODEBUDDY_PATH | Custom path to the codebuddy binary |
AACWORKFLOW_CODEBUDDY_MODEL | Override the CodeBuddy model used |
AACWORKFLOW_ANTIGRAVITY_PATH | Custom path to the agy binary |
AACWORKFLOW_ANTIGRAVITY_MODEL | Override the Antigravity model used |
AACWORKFLOW_QODER_PATH | Custom path to the qodercli binary |
AACWORKFLOW_QODER_MODEL | Override the Qoder model used |
AACWORKFLOW_TRAECLI_PATH | Custom path to the traecli binary |
AACWORKFLOW_TRAECLI_MODEL | Override the Trae model used |
Profiles
Profiles let you run multiple daemons on the same machine — for example, one for production and one for a staging environment.
# Set up a staging profile
aacworkflow setup --profile staging
# Start its daemon
aacworkflow daemon start --profile staging
# Default profile runs separately
aacworkflow daemon startEach profile gets its own config directory (~/.aacworkflow/profiles/<name>/), daemon state, health port, and workspace root.
Workspaces
List Workspaces
aacworkflow workspace listWatched workspaces are marked with *. The daemon only processes tasks for watched workspaces.
Watch / Unwatch
aacworkflow workspace watch <workspace-id>
aacworkflow workspace unwatch <workspace-id>Get Details
aacworkflow workspace get <workspace-id>
aacworkflow workspace get <workspace-id> --output jsonList Members
aacworkflow workspace member list <workspace-id>Update Workspace
需要 admin 或 owner 权限。所有字段都是部分更新（PATCH 语义）：未传的字段保持不变。
aacworkflow workspace update <workspace-id> --name "Acme Eng"
aacworkflow workspace update <workspace-id> \
--description "Engineering team workspace" \
--issue-prefix ENG长文本走 stdin（保留换行/反斜杠）：
cat <<'CTX' | aacworkflow workspace update <workspace-id> --context-stdin
我们是一支 5 人 AI-native 团队。
工作语言：中文 + 英文混合。
CTX可编辑字段：--name、--description / --description-stdin、--context / --context-stdin、--issue-prefix。slug 创建后只读，不暴露在 CLI。--description 与 --description-stdin（以及 context 同名对）互斥。未传任何字段 flag 时命令拒绝执行，避免空 PATCH 触发无意义的 workspace 更新事件。--issue-prefix "" 也会被拒绝：当前后端在 prefix 为空时静默跳过该字段，CLI 在本地拦下避免“看似成功的 no-op”。
Issues
List Issues
aacworkflow issue list
aacworkflow issue list --status in_progress
aacworkflow issue list --priority urgent --assignee "Agent Name"
aacworkflow issue list --assignee-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
aacworkflow issue list --full-id
aacworkflow issue list --limit 20 --output json表格输出默认显示可直接复制到后续命令的 issue KEY（例如 AAC-123）；需要完整 UUID 时使用 --full-id。Available filters: --status, --priority, --assignee / --assignee-id, --project, --limit. 在重名 workspace 下用 --assignee-id <uuid> 可以精确锁定一个成员或 agent。
Get Issue
aacworkflow issue get AAC-123
aacworkflow issue get <uuid>
aacworkflow issue get <id> --output json<id> 同时接受 issue key（aacworkflow issue list 表格里直接显示，例如 AAC-123）和完整 UUID（给 list 加 --full-id 可显示）。同样的规则适用于下面 update / assign / status / comment / subscriber / runs 等接受 <id> 的命令。
Create Issue
aacworkflow issue create --title "Fix login bug" --description "..." --priority high --assignee "Lambda"
aacworkflow issue create --title "Fix login bug" --assignee-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545dFlags: --title (required), --description, --status, --priority, --assignee / --assignee-id, --parent, --project, --due-date. 脚本里如果已经拿到了 UUID（例如来自 aacworkflow workspace member list --output json），传 --assignee-id <uuid>（与 --assignee 互斥）以精确锁定。
Update Issue
aacworkflow issue update <id> --title "New title" --priority urgentAssign Issue
aacworkflow issue assign <id> --to "Lambda"
aacworkflow issue assign <id> --to-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
aacworkflow issue assign <id> --unassign--to-id <uuid>（与 --to 互斥）按 UUID 精确分配；适合重名 workspace 下脚本化场景。
Change Status
aacworkflow issue status <id> in_progressValid statuses: backlog, todo, in_progress, in_review, done, blocked, cancelled.
Comments
# List comments
aacworkflow issue comment list <issue-id>
# Add a comment
aacworkflow issue comment add <issue-id> --content "Looks good, merging now"
# Reply to a specific comment
aacworkflow issue comment add <issue-id> --parent <comment-id> --content "Thanks!"
# Delete a comment
aacworkflow issue comment delete <comment-id>Execution History
# List all execution runs for an issue
aacworkflow issue runs <issue-id>
aacworkflow issue runs <issue-id> --full-id
aacworkflow issue runs <issue-id> --output json
# View messages for a specific execution run
aacworkflow issue run-messages <task-id>
aacworkflow issue run-messages <short-task-id> --issue <issue-id>
aacworkflow issue run-messages <task-id> --output json
# Incremental fetch (only messages after a given sequence number)
aacworkflow issue run-messages <task-id> --since 42 --output jsonruns 的表格输出默认显示 task UUID 短前缀；需要完整 task UUID 时使用 --full-id。run-messages 可直接接受完整 task UUID；从 runs 表格复制短前缀时需要同时传 --issue <issue-id>，CLI 只会在该 issue 的 runs 内解析。
Projects
Projects group related issues (e.g. a sprint, an epic, a workstream). Every project belongs to a workspace and can optionally have a lead (member or agent).
List Projects
aacworkflow project list
aacworkflow project list --status in_progress
aacworkflow project list --output jsonAvailable filters: --status.
Get Project
aacworkflow project get <id>
aacworkflow project get <id> --output jsonCreate Project
aacworkflow project create --title "2026 Week 16 Sprint" --icon "🏃" --lead "Lambda"Flags: --title (required), --description, --status, --icon, --lead.
Update Project
aacworkflow project update <id> --title "New title" --status in_progress
aacworkflow project update <id> --lead "Lambda"Flags: --title, --description, --status, --icon, --lead.
Change Status
aacworkflow project status <id> in_progressValid statuses: planned, in_progress, paused, completed, cancelled.
Delete Project
aacworkflow project delete <id>Associating Issues with Projects
Use the --project flag on issue create / issue update to attach an issue to a
project, or on issue list to filter issues by project:
aacworkflow issue create --title "Login bug" --project <project-id>
aacworkflow issue update <issue-id> --project <project-id>
aacworkflow issue list --project <project-id>Configuration
View Config
aacworkflow config showShows config file path, server URL, app URL, and default workspace.
Set Values
aacworkflow config set server_url wss://api.example.com/ws
aacworkflow config set app_url https://app.example.com
aacworkflow config set workspace_id <workspace-id>Other Commands
aacworkflow version # Show CLI version and commit hash
aacworkflow update # Update to latest version
aacworkflow agent list # List agents in the current workspaceOutput Formats
Most commands support --output with two formats:
table— human-readable table (default for list commands)json— structured JSON (useful for scripting and automation)
aacworkflow issue list --output json
aacworkflow daemon status --output json