CLI Commands

The agentteams CLI manages platform entities — plans, reports, co-actions, and more — from your terminal.


agentteams <command> <action> [options]
agentteams --help             # all commands
agentteams <command> --help   # actions/options per command

Command list

Command	Description
`init`	Initialize the CLI via OAuth (creates `.agentteams/`)
`sync`	Force-sync conventions and skills, no change check
`session`	Session-start sync (`session sync`) and its hook (`session hook`)
`guide`	Read platform guides (`guide list` / `get`)
`doctor`	Diagnose convention reachability, install worktree hook
`plan`	Manage plans
`task`	Manage plan tasks
`comment`	Manage plan comments
`report`	Manage completion reports
`coaction`	Manage co-actions (session context)
`postmortem`	Manage post-mortems
`code-review`	Manage independent code reviews
`convention`	Manage project conventions
`document`	Manage project documents
`dependency`	Manage plan dependencies
`change-set`	Manage cross-repository change sets and merge order
`agent-config`	Manage agent configurations
`attachment`	Manage runner request and document attachments
`feedback`	Manage platform feedback
`config`	Manage CLI configuration
`search`	Search across all entity types
`resolve`	Detect an entity reference’s type and resolve it
`linear`	Read/comment on Linear issues
`mcp`	Run the MCP server and register clients
`worktree`	Report Orca worktree lifecycle events

Action pattern

Most commands take an <action>. The common actions are list, get, create, update, delete, with domain-specific actions added per command.


# Plans: start, finish, quick, assign, download, link-document, etc. on top of CRUD
agentteams plan list
agentteams plan start --id <planId>
agentteams plan finish --id <planId> --report-title "..." --report-file <path> \
  --runner-type CLAUDE_CODE --model <model-id> --quality-score 90 --report-status COMPLETED
 
# Completion reports
agentteams report create --plan-id <planId> --title "..." --file <path> \
  --runner-type CLAUDE_CODE --model <model-id>
 
# Unified search
agentteams search --query "<keyword>"
agentteams search --query "<keyword>" --types BITBUCKET_ISSUE,BITBUCKET_PR

See Plans for plan lifecycle rules and Code Review for review workflow.

Session-start hook

session hook install adds a SessionStart hook to your Claude Code settings file so that agentteams session sync runs automatically every time a Claude Code session starts. session hook uninstall removes only the AgentTeams hook and leaves the settings file and every other setting in place.


agentteams session hook install                     # project scope: .claude/settings.json
agentteams session hook install --scope user --yes  # user scope: ~/.claude/settings.json
agentteams session hook install --dry-run           # print the target file and change without writing
agentteams session hook uninstall
agentteams init --session-hook                      # install at project scope while initializing

install and uninstall take the same options.

Option	Description
`--client <id>`	Target client. `claude-code` (default)
`--scope <scope>`	`project` (default) or `user`
`--yes`	Approves editing the user-level settings file. Required for `--scope user`
`--dry-run`	Prints the target file and the change without writing anything
`--cwd <path>`	Explicit directory for `--scope project` (default: detected project root, or current directory)

init --session-hook installs the hook at project scope only when Claude Code is detected. If it is not detected, no settings file is written and the manual install command (agentteams session hook install) is shown instead.

The hook runs agentteams session sync --hook claude-code. --hook claude-code prints the sync result in the format Claude Code takes in as session context. For how the scopes differ and what happens when you share the hook with a team, see CLI — Automate session-start sync.

Linking plans and documents

Use plan link-document to link a document from the document library to a plan, and plan unlink-document to remove the link. List the links from the plan side with plan list-documents, or from the document side with document list-plans.


agentteams plan link-document --id <planId> --document-id <documentId> --note "Design rationale"
agentteams plan list-documents --id <planId>
agentteams document list-plans --id <documentId>
agentteams plan unlink-document --id <planId> --document-id <documentId>

Linking a document that is already linked finishes without an error as Document already linked (skipped). Unlinking does not delete the document.

Document attachments

Use --document-id with the attachment command to add files to a document or list its attachments. Use an attachment ID from the list to download or delete the file.


agentteams attachment create --document-id <documentId> --file ./guide.pdf
agentteams attachment list --document-id <documentId>
agentteams attachment download --id <attachmentId> --dest ./downloads/
agentteams attachment delete --id <attachmentId>

For create, use exactly one of --document-id, --code-review-id, or --completion-report-id. For list, use exactly one of --document-id, --trigger-id, --code-review-id, or --completion-report-id.

download works for attachments on documents, runner requests, code reviews, and completion reports. Without --dest, the file is saved in the current directory under its original name. If --dest is an existing directory, the file is saved inside it; any other path is used as the file path. If a file with the same name already exists, the command stops with File already exists; add --force to overwrite it.

delete removes document attachments only. Attachments on other targets are rejected with Only document attachments can be deleted.