CLI command reference

This reference covers the production alterac-ai commands people use to set up a repository, manage authentication and trust, and run local work. Local coding agents also use CLI commands when their repository guidance directs them; their command contracts remain in that guidance.

alterac-ai --help
alterac-ai --version
alterac-ai <command> --help
alterac-ai <branch> <command> --help

Use built-in help rather than guessing syntax. alterac-ai --version prints the exact embedded product release version and does not read repository state or contact the API. The CLI installation guide provides the current stable archives and manual setup, while the CLI overview explains how the commands fit together.

After an ordinary command is parsed successfully, the CLI may print one warning when fresh cached release metadata shows that the installed stable version is older. The warning links to the manual CLI installation guide; it never installs an update. The warning uses standard error, so --json standard output remains valid structured data. Release checks are periodic and best effort, run without delaying the requested command, and do not change its exit result. Help, --version, and invalid command lines do not print this binary-version warning.

Authenticated commands keep stored credentials when the API denies access. When an organization's license has expired, the CLI prints the API's stable recovery guidance instead of replacing it with a generic permission message. New product operations remain blocked until reactivation, while an exact work run that already started can still use work-run get and work-run complete to reach review safely.

alterac-ai init is normally person-operated. It has no required arguments. It authenticates if needed, selects an accessible project, selects coding-agent trust and managed instruction files, refreshes repository-local guidance, and writes .alterac-ai/config.yaml. If no accessible project is available, create or join one in alterac.ai and retry.

alterac-ai docs-update [--force] refreshes the repository-local alterac.ai home using the existing managed instruction-file selection. --force requests a refresh even when the local version looks current. Both commands change repository-local state, not project tasks. See Initialize and refresh repository guidance for the workflow.

alterac-ai config trust is normally person-operated and interactive. It reads the local trust mode, asks for a replacement, and saves it to .alterac-ai/config.yaml. It controls local coding-agent command-template approval, not project permission.

alterac-ai login is normally person-operated and interactive. It collects email, password, and required two-factor or recovery-code challenges, then stores CLI authentication for the device. alterac-ai logout clears that stored authentication and succeeds with a no-op message when none exists.

Authenticated commands other than init report missing or rejected credentials and direct you to login; they do not begin an unexpected interactive sign-in. Read Log in and out from the CLI for recovery.

alterac-ai listen [--poll-interval-seconds <seconds>]

The person-operated listener reads the configured project, authenticates, registers local presence, polls queued work, captures immutable context, and launches the selected coding-agent command. The polling interval defaults to 5 seconds and must be from 1 through 300. Ctrl+C stops the listener. When a terminal cannot be launched, it prints the resolved command for manual use. See Listen for queued work.

alterac-ai labels [--project <projectId>] [--json]

This normally agent-operated command lists project-owned and inherited organization labels. Without --project, it reads the selected project from .alterac-ai/config.yaml; an explicit accessible project does not change that file. Default output is Markdown with names and stable IDs; JSON also includes scope and ownership details.

alterac-ai task create [taskMarkdown] --title <text> [--file <path>] [--mass <number>] [--exclude-from-metrics] [--label <labelNameOrId>]... [--dependency <taskNumber>]... [--plan <planNumber>] [--assignee <emailOrUserId>] [--project <projectId>] [--json]

This command immediately creates one normal Backlog task. It requires a nonblank title and Markdown supplied inline or with --file, but never both. It does not queue work or create a work run. Use Task Builder when you need to create multiple new tasks or review related work before publishing it.

Pass --exclude-from-metrics to record that a new task should be excluded from task-derived metrics; omission records it as included. The created task output reports the persisted choice, and task-derived reports apply it retroactively without changing lifecycle or history.

--mass must be below 100. Repeat --label to assign exact available labels and --dependency to set direct project task dependencies. --plan accepts an active project-scoped Plan number. --assignee accepts an exact eligible member email, display name, or stable user ID. The API authoritatively validates permissions, labels, dependencies, Plan membership, and assignee eligibility. The default output is the created task; --json returns the same authoritative task data as JSON. If separately stored labels or assignee metadata cannot be applied after creation, the error names the created task and the exact metadata operation to review and retry.

alterac-ai task list [--project <projectId>] [--plan <planNumber>] [--json]

This normally agent-operated command lists tasks in ascending task-number order. It reads the selected project from .alterac-ai/config.yaml unless --project supplies another accessible project, without changing local selection. Use --plan with a positive project-scoped Plan number to list that Plan's current tasks; an unavailable Plan returns an error, while an available Plan with no tasks returns a successful empty list. Markdown shows each task's number, title, state, Mass, metric exclusion, labels, Plan, dependency status, assignee, and update time. --json returns the same authoritative task records for scripting. The command is read-only.

alterac-ai task get <taskNumber> [--project <projectId>] [--json]

This normally agent-operated command reads complete authoritative task content and metadata without changing task state. taskNumber is a positive, project-scoped number; it is not the task's GUID or an exact taskWorkRunId. The project comes from local config unless --project supplies another accessible project. Default Markdown includes the task and project IDs, title, Markdown, state, Mass, metric exclusion, labels, dependencies, blocking tasks, Plan, assignee, timestamps, completion facts, and active-work-run context. --json returns the equivalent structured response. It does not retrieve comments or review history. Use it before a direct task update or deletion.

alterac-ai task delete <taskNumber> [--project <projectId>] [--yes]

This destructive command retrieves one authoritative published task before deleting it. Interactive use displays the exact task number and title, then asks for default-negative confirmation. Declining or providing no affirmation leaves the task unchanged and reports that it was not deleted.

Use --yes as the explicit affirmative option for an asynchronous coding agent or another non-interactive invocation. It skips only the prompt: the CLI still retrieves the task and the API still owns authentication, access, deletion eligibility, relationships, dependencies, work runs, comments, reviews, and provenance. Success appears only after API confirmation. A task that disappears after retrieval reports not-found instead of success, while server rejection and API failures return distinct errors.

Deletion is immediate and has no soft-delete or restore path. This removes a published project task; it does not affect unpublished Task Builder drafts.

alterac-ai task update <taskNumber> [taskMarkdown] [--title <text>] [--file <path>] [--mass <number> | --clear-mass] [--exclude-from-metrics | --include-in-metrics] [--label <labelNameOrId>]... [--clear-labels] [--dependency <taskNumber>]... [--clear-dependencies] [--plan <planNumber> | --clear-plan] [--assignee <emailOrUserId> | --clear-assignee] [--project <projectId>] [--json]

This command immediately updates one published task. It requires a positive project-scoped task number and at least one explicit replacement or clear. Omitted fields preserve current values. --title, inline Markdown, and --file replace required content and cannot clear it. Use inline Markdown or --file, never both.

Each metadata field follows the same preserve, replace, and clear convention. Omit it to preserve it. Pass --mass <number>, repeated --label, repeated --dependency, --plan <planNumber>, or --assignee <emailOrUserId> to replace that complete field. Pass the corresponding --clear-mass, --clear-labels, --clear-dependencies, --clear-plan, or --clear-assignee option to clear it. Do not combine replacement and clear options for the same field.

Pass --exclude-from-metrics or --include-in-metrics to replace the persisted task-level metric eligibility choice. Omit both to preserve it, and never pass both together. Task-derived reports apply the choice retroactively. The command uses the task version it just retrieved and rejects a stale concurrent change instead of overwriting it.

Labels must be exact available labels and enforce scoped exclusivity. Dependencies use task numbers and enforce availability, self-dependency, duplicate, and cycle rules. Plans use one active same-project Plan number. Assignees use an exact eligible member email, display name, or stable user ID. The API remains authoritative for project access and metadata validation.

Default output is the complete authoritative persisted task; --json returns the same task data as JSON. When coordinated metadata endpoints partially fail, the command exits nonzero, names completed and failed operations, and returns authoritative recovery state when it can retrieve it. Review that state and retry only the remaining field.

Workflow state is not generic task metadata. This command preserves state, comments, reviews, work runs, completion facts, and Task Builder provenance. It does not queue work, transition review state, edit a Plan, add comments, or complete a work run; use the workflow-specific task, review, and work-run actions for those lifecycle changes.

alterac-ai task comment <taskNumber> [commentMarkdown] [--file <path>] [--author <agent|person>] [--project <projectId>]

This normally agent-operated command adds one nonblank Markdown comment without changing task state. taskNumber is a positive project-scoped integer. Provide inline Markdown or --file, never both. --author defaults to agent; use person only to preserve a direct human comment. The project comes from local config unless --project is supplied. See Use task and work-run commands.

alterac-ai work-run get <taskWorkRunId> [--json]
alterac-ai work-run complete <taskWorkRunId> (--summary <markdown> | --summary-file <path>) (--hand-off <markdown> | --hand-off-file <path>) [--review-url <url>]

These normally agent-operated commands use an exact, non-empty work-run GUID supplied by the listener. They authenticate but do not read project configuration or accept a project override. get returns immutable execution context as Markdown by default or JSON with --json; it does not fall back to task data. Both forms expose the durable execution origin and the nullable Plan context captured when the run started, including Plan identity, content, archive state, timestamps, and labels. Markdown adds a prominent restart instruction for FreshStart and a separate Plan Snapshot section; JSON returns the typed executionOrigin and nullable plan values. A task that was standalone at start remains without Plan context even if its live membership changes later.

complete requires nonblank summary and AI hand-off content, with exactly one inline or file form for each. It may include an absolute HTTP or HTTPS review URL no longer than 2,048 characters. It retrieves the same immutable context, submits review output for that exact run, and reports the task state. Only run it after implementation, validation, and delivery are complete. A taskNumber cannot substitute for a taskWorkRunId.

Use an inline value or a file for Markdown input, not both. Required task/comment/work-run files must contain nonblank text; proposed Plan Markdown is optional and an omitted or empty value stores empty Markdown. Use files for multiline or shell-sensitive content and remove temporary files after use. Default output is Markdown or concise status text; use --json only on commands that list it. A nonzero exit is not a partial success.

Project-scoped commands, including task list, task get, and task comment, read projectId from .alterac-ai/config.yaml unless they offer and receive --project <projectId>. The local config may also store trust, managed instruction-file selection, and an active Task Builder session. Use CLI commands, not hand edits, to change it.