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 one-line installation, version selection, rerun upgrades, and uninstall steps, while the CLI overview explains how the commands fit together.

Scheduling examples require an executable whose help lists the relevant milestone, task membership/filter/classification, or Task Builder scheduling command. If your installed help lacks one, follow Check scheduling command availability before using the example. Refreshing generated guidance does not upgrade the executable.

After an ordinary command is parsed successfully, including init and docs-update, the CLI checks whether a newer stable version is available before running the command. Successful checks are reused for 15 minutes; a due check waits at most two seconds for release metadata. Failed checks retry no sooner than one minute later and do not change the command's exit result. A previously verified newer version continues to produce a warning if a later check fails.

The warning names the installed and available versions and links to the CLI installation guide; it never installs an update. It appears in yellow when the terminal supports color and uses standard error, so --json standard output remains valid structured data. If generated repository guidance is also outdated, its separate warning follows the CLI warning. init and docs-update refresh that guidance themselves and skip only its warning. Help, --version, and invalid command lines do not check for or 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, expands the selected command's {alterac-ai-message} token into the centrally owned exact-run instruction, and launches the command. A snapshot without the required token fails before launch with requeue guidance. 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>] [--type <coding-agent|person>] [--mass <number>] [--weight <number>] [--exclude-from-metrics] [--label <labelNameOrId>]... [--dependency <taskNumber>]... [--plan <planNumber>] [--sprint <sprintNumber>] [--sprint-change <correction|scope-change>] [--milestone <milestoneNumber>] [--milestone-change <correction|scope-change>] [--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 sizes a Coding agent task and --weight sizes a Person task; both must be below 100. Use --mass only with --type coding-agent (or the default type) and --weight only with --type person; the mismatched option, or both options together, fails before any request. Repeat --label to assign exact available labels and --dependency to set direct project task dependencies. --plan accepts an active project-scoped Plan number. --sprint and --milestone accept available same-project Planned or Current records while their respective features are enabled; Current assignment requires its own --sprint-change or --milestone-change. See Sprint membership and estimate changes and Milestone membership and estimate changes. --assignee accepts an exact eligible member email, display name, or stable user ID. Permissions, labels, dependencies, Plan, Sprint, and Milestone membership, and assignee eligibility are validated before mutation. Task creation and its Sprint/Milestone assignments save together after target, lifecycle, authority, and classification preflight. The default output is the created task, including its persisted type and ordered compatible states, shown as Weight for a Person task and Mass for a Coding agent task; --json uses mass for both types. Omit --type or use --type coding-agent for a Coding agent task; use --type person for a Person task. The chosen type cannot be changed after creation. 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>] [--sprint <sprintNumber>] [--milestone <milestoneNumber>] [--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, --sprint, or --milestone with a positive project-scoped number to list current members; combined filters require every selected membership. An unavailable target returns an error, while an available target with no current tasks returns a successful empty list. Each scheduling filter requires its own feature to be enabled and does not list historical Complete membership. Markdown shows each task's number, title, persisted type, current state, ordered compatible states, Weight or Mass (by type), metric exclusion, labels, Plan, current Sprint and Milestone, dependency status, assignee, and update time. --json returns the same authoritative task records, with the sizing value as mass for both types, for scripting. Current Sprint and Milestone metadata include identity and lifecycle; Sprint detail also includes planned dates and opening or closing facts. A disabled feature hides its scheduling details independently. Markdown lifecycle labels are Planned, Current, and Complete; JSON preserves the API states Planned, Started, and Complete. Legacy records and omitted creation types retain Coding agent compatibility. 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, persisted type, current state, ordered compatible states, Weight or Mass (by type), metric exclusion, labels, dependencies, blocking tasks, Plan, current Sprint and Milestone identity and lifecycle facts when enabled, assignee, timestamps, completion facts, and active-work-run context. --json returns the equivalent structured response, with the sizing value as mass for both types. 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] [--weight <number> | --clear-weight] [--exclude-from-metrics | --include-in-metrics] [--label <labelNameOrId>]... [--clear-labels] [--dependency <taskNumber>]... [--clear-dependencies] [--plan <planNumber> | --clear-plan] [--sprint <sprintNumber> | --clear-sprint] [--sprint-change <correction|scope-change>] [--milestone <milestoneNumber> | --clear-milestone] [--milestone-change <correction|scope-change>] [--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>, --weight <number>, repeated --label, repeated --dependency, --plan <planNumber>, --sprint <sprintNumber>, --milestone <milestoneNumber>, or --assignee <emailOrUserId> to replace that complete field. Pass the corresponding --clear-mass, --clear-weight, --clear-labels, --clear-dependencies, --clear-plan, --clear-sprint, --clear-milestone, or --clear-assignee option to clear it. Do not combine replacement and clear options for the same field. Sprint or Milestone replacement changes only that feature’s membership; Plan and other metadata remain independent.

--mass/--clear-mass apply only to a Coding agent task and --weight/--clear-weight only to a Person task; the command validates the supplied option against the task's retrieved type before any write and fails with a task-specific message when it does not match, or when both a mass option and a weight option are supplied together.

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, including its type and ordered compatible states; --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 and task type are not generic task metadata. This command preserves both, along with 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. Person lifecycle transitions are available in the application; the CLI has no Person start, submission, or review-resolution commands.

alterac-ai task-builder show <SESSION-NUMBER> [--json]
alterac-ai task-builder task update <DRAFT-ID> [MARKDOWN] --title <TEXT> [--expected-updated-at <TIMESTAMP>] [--file <PATH>] [--mass <NUMBER> | --weight <NUMBER>] [--session <SESSION-NUMBER>]

Read and review the draft before preparing an update. For stale-write protection, pass that draft's exact updatedAt as the optional --expected-updated-at; human show output also prints a copyable option. Use the draft timestamp, rather than the session timestamp. The command requires a complete title and Markdown, supplied inline or through --file. It preserves the current task type, Plan membership, labels, and dependencies. Coding agent drafts accept --mass; Person drafts accept --weight. Omitting the matching sizing option clears the saved value. The Building browser editor can change draft type and same-session relationships; this CLI content command has no type-conversion option.

Without a version, the previous last-write-wins behavior is preserved and can overwrite newer saved content. With a version, if the draft changes after your read, the update is rejected without overwriting the newer content. Run alterac-ai task-builder show <SESSION-NUMBER>, review the current draft, merge your intended changes, then retry with its newly reviewed updatedAt. The command never replaces your token with its internal session read or automatically retries a stale replacement. Published sessions remain read-only. Archiving only changes visibility; an archived Building session remains editable.

Older CLIs remain supported without this option. To use version-checked updates, check that task-builder task update --help lists --expected-updated-at; install an available release if needed. Refreshing generated guidance does not upgrade the executable. See Edit draft content for browser and AI collaboration.

alterac-ai task-builder show <SESSION-NUMBER> [--json]
alterac-ai task-builder task set-labels <DRAFT-ID> [--expected-updated-at <TIMESTAMP>] [--label <ID-OR-NAME>]... [--session <SESSION-NUMBER>] [--json]
alterac-ai task-builder task set-dependencies <DRAFT-ID> [--expected-updated-at <TIMESTAMP>] [--dependency <DRAFT-ID>]... [--session <SESSION-NUMBER>] [--json]
alterac-ai task-builder task set-plan <DRAFT-ID> [--expected-updated-at <TIMESTAMP>] [--plan <PLAN-ID>] [--session <SESSION-NUMBER>] [--json]

Each command replaces its complete relationship field on one Building draft. set-labels accepts available project or inherited organization label IDs or exact names; set-dependencies accepts other draft IDs from the same session; set-plan accepts a proposed Plan ID from that same session. Omit the relationship options to clear labels or dependencies, or return the draft to Standalone. The optional --expected-updated-at also protects clearing.

Before preparing any replacement, run show and review the draft's current type, content, size, Plan membership, labels, and dependencies. For stale-write protection, pass that draft's exact earlier reviewed updatedAt as optional --expected-updated-at, rather than the session timestamp. Internal lookups preserve the supplied token. Unversioned replacements retain the previous last-write-wins behavior and can overwrite newer selections; supplied stale versions reject the replacement without changing newer browser or CLI selections. After a conflict, run show again, review and merge the intended changes, and retry explicitly with the newly reviewed draft version. Do not automatically refresh the token and resend an old replacement.

Older CLIs remain supported for these commands. To use version-checked replacements, check each command’s help for --expected-updated-at and install an available release if needed. Updating repository guidance alone does not upgrade the executable. See Refine draft content and relationships for collaboration and recovery.

alterac-ai task-builder task set-sprint <DRAFT-ID> [--sprint <SPRINT-NUMBER>] [--session <SESSION-NUMBER>] [--json]
alterac-ai task-builder show <SESSION-NUMBER> [--json]

This normally agent-operated command assigns or replaces a Building draft's future Sprint membership. Omit --sprint to clear it. DRAFT-ID is stable; SPRINT-NUMBER must be a positive number within the configured project, available from its Sprints page. Omit --session to use the active Building session or select one explicitly without changing local selection. Plan membership and dependencies are independent, and both fixed draft task types are supported.

Targets must be Planned with Sprints enabled. Disabled configuration returns Project Settings recovery; missing, inaccessible, or cross-project targets return access/identity guidance. Current or Complete targets (Started or Complete in JSON output) must be replaced with a future Planned Sprint or cleared before publication. A failed replacement preserves the saved assignment. Clearing does not require an enabled or available target.

Default output and detailed session reads show Sprint number, title, current state, and stable ID. --json exposes the saved sprintId and nullable sprint object with sprintId, number, title, and state; unavailable details retain the saved ID. The command reads current session state after mutation, and later server readiness and publication responses remain authoritative if eligibility changes. This command creates no Sprints, changes no lifecycle, and does not publish the session. See Refine proposed Plans and draft tasks and Review and publish a session.

alterac-ai task-builder task set-milestone <DRAFT-ID> [--milestone <MILESTONE-NUMBER>] [--milestone-change <correction|scope-change>] [--session <SESSION-NUMBER>] [--json]
alterac-ai task-builder show <SESSION-NUMBER> [--json]

This normally agent-operated command assigns or replaces one Building draft's Milestone target. Omit --milestone and --milestone-change to clear both the target and saved intent. Use the stable draft ID and a positive Milestone number from this project's Milestones page. Omit --session to use the active Building session, or select another explicitly without changing local selection. Coding agent and Person drafts are supported; Sprint and Plan membership remain independent.

An enabled same-project Planned target requires no intent and rejects --milestone-change. A Started target (Current in scheduling rules) requires explicit --milestone-change correction or --milestone-change scope-change. Scope change records newly added work. Correction requires Team Lead authority and counts the published task in the opening plan, even when publication happens later. Its actual creation and completion times stay unchanged. Choose Scope change when the work should enter scope at publication time. The server remains authoritative for permission, readiness, and publication checks.

Complete, missing, inaccessible, or cross-project targets are invalid. Failed assignment or replacement preserves the previous target and intent. If the target becomes Complete or unavailable, select another eligible target or clear both fields. If a Planned target becomes Started, explicitly save Current intent before publishing. Assignment and replacement fail when Milestones are disabled with Project Settings guidance; clearing stale draft intent remains available to an authorized session editor, including when the target is unavailable. Clearing a draft never changes live Milestone membership.

Human output and detailed session reads report target number, title, lifecycle (Planned, Current, or Complete; Current is Started in JSON), stable ID, and saved intent. --json retains milestoneId, milestoneChangeKind (Correction, ScopeChange, or null), and nullable milestone context (milestoneId, number, title, state, version). Unavailable target details preserve the saved ID and intent. Output refreshes session facts after a successful mutation; readiness and publication recheck them. This command does not publish, change a Milestone lifecycle, or delete a Milestone. See Recover saved Milestone intent and Resolve saved Milestone intent.

Sprint numbers are positive and scoped to the selected project. Assignment accepts Planned or Current Sprints; Complete Sprints cannot receive current members. Closing a Sprint clears its current membership, retaining history. The CLI exposes current membership, not historical correction controls or Sprint entity creation, opening, closing, or deletion commands.

Planned membership needs no classification. For a membership change involving a Current Sprint or an actual estimate change affecting Current planning history, supply --sprint-change correction or --sprint-change scope-change. One choice covers the whole Sprint change across the affected source and destination histories and any simultaneous Mass or Weight change. A Correction repairs the opening membership and Size plan and requires effective Team Lead authority; it may include a later-created task without changing its actual creation, state, or completion times. A Scope change records a later scope decision and is available to effective project members. Setting a missing estimate or clearing an estimate counts as a change. The classification option requires a membership or estimate mutation and does not perform a standalone change.

Requested targets and classifications are validated before any write. Task creation with Sprint assignment, and task updates to content, dependencies, Sprint membership, and affected estimate history, save atomically. Invalid or stale Sprint changes leave that operation unchanged. Plan, labels, assignee, and metric eligibility may use separate writes; review recovered authoritative task output if a later write fails.

An actual estimate edit affecting Current Milestone history additionally requires --milestone-change correction or --milestone-change scope-change, with the same Correction and Scope change permissions. Supply independent choices when both Sprint and Milestone history are affected; Correction in one and Scope change in the other is valid. All affected histories are validated and saved atomically. Setting a missing estimate or clearing one counts as a change. Milestones must be enabled to submit their classification; if disabled, re-enable them before the edit.

When Sprints are disabled, assignment, replacement, clearing, filtering, and standalone classification are rejected with Project Settings guidance. Ordinary task edits remain available. An actual estimate edit affecting retained Current Sprint history still requires the same explicit classification and authority, with neutral planning-history guidance that does not disclose the disabled Sprint's details. If that edit also affects a disabled Milestone, its classification is blocked and the whole edit waits for Milestone re-enablement. Task Builder supports independent future Planned Sprint membership and Planned or Started Milestone membership.

Use --milestone <milestoneNumber> on task creation or update to assign one available same-project Milestone. On update, omission preserves membership and --clear-milestone clears it; replacement and clear are mutually exclusive. Plan, Sprint, and Milestone membership remain independent. Use task list --milestone <milestoneNumber> for current members, optionally combined with --plan and --sprint; every selected membership must match. An available target with no current members succeeds with an empty list.

Planned membership needs no classification. A membership change involving a Started Milestone, or an actual Mass or Weight edit affecting its history, requires --milestone-change correction or --milestone-change scope-change. One choice covers the whole Milestone change across affected source/destination records and the simultaneous estimate edit. Scope change records a later scope decision and is available to project members. Correction repairs the opening plan and requires Team Lead authority. It may include a newly created task; its actual creation, state, and completion dates remain unchanged. Scope change instead adds work from the time of the change. A classification alone is not a task or history mutation.

The command preflights feature settings, project/lifecycle eligibility, authority, and intent before task creation. The API revalidates at the atomic write boundary: task content, dependencies, memberships, and every affected Sprint/Milestone history save together. Invalid targets, unavailable history evidence, unauthorized Corrections, and stale versions leave that operation unchanged. Plan, labels, assignee, or metric updates may use separate writes; review returned authoritative task output if a later operation fails.

Complete Milestones cannot receive live tasks. Completion clears current membership and retains final history; later live estimate edits do not rewrite that snapshot. Explicit historical repairs belong to the history-correction workflow, rather than assigning a task to a Complete record. Milestone opening, closing, and eligible deletion remain browser operations.

When Milestones are disabled, assignment, replacement, clearing, filtering, and --milestone-change fail with Project Settings guidance while records/history remain intact. An estimate edit affecting retained Started Milestone history also requires re-enablement before its explicit classification; rejection leaves the task and all affected histories unchanged. Ask a Team Lead to re-enable Milestones before retrying. Enabled Sprint workflows remain available independently.

alterac-ai milestone create [MARKDOWN] --title <TITLE> --target <DATE-OR-TIMESTAMP> [--file <PATH>] [--project <PROJECT-GUID>] [--json]
alterac-ai milestone list [--project <PROJECT-GUID>] [--json]
alterac-ai milestone get <MILESTONE-NUMBER> [--project <PROJECT-GUID>] [--json]
alterac-ai milestone update <MILESTONE-NUMBER> [MARKDOWN] [--title <TITLE>] [--file <PATH>] [--target <DATE-OR-TIMESTAMP>] [--project <PROJECT-GUID>] [--json]

These commands create, discover, read, and edit project Milestone metadata. create requires a nonblank title, a nonblank Markdown objective supplied inline or with --file, and a target. It creates a Planned Milestone without opening it or assigning tasks. Use inline Markdown or a file, never both. get and update use a positive project-scoped Milestone number, not a Milestone GUID or task number.

--target accepts YYYY-MM-DD as an organization-local calendar date, or an ISO 8601 timestamp with an explicit offset or Z, such as 2026-12-18T17:00:00-05:00. A date covers that local day through the next local midnight as an exclusive boundary; the stored target retains its time-zone interpretation. A timestamp without an offset is rejected.

update first retrieves the current record and requires at least one explicit title, objective, or target replacement. Omitted fields preserve current values. Required fields cannot be cleared or replaced with blank text. The API checks the retrieved record version; if someone changes it before your save, reload with get, review their changes, and retry only the intended replacement. Project members can read enabled records, create Milestones, and edit Planned metadata. Editing Started or Complete records requires Team Lead authority or inherited organization Owner/Admin project-management authority; updates preserve lifecycle and history.

Default Markdown and --json output include Milestone and project identity, title, lifecycle, objective, target and time-zone context, and concise eligible task-count progress facts with excluded-member coverage. Complete progress uses the corrected historical final scope and retained task states, together with the current metric-exclusion choice. A retained membership Correction changes these counts without changing live task membership. Later task deletion retains the last recorded metric-exclusion choice, so available history still reports the corrected final scope. If the latest exclusion choice or historical evidence cannot be verified, progress is unavailable. Markdown lifecycle labels are Planned, Current, and Complete; JSON preserves the API states Planned, Started, and Complete. Detail output also includes creation, update, opening, and closing timestamps, with Started and Completed as the opening and closing timestamp labels in Markdown. These are factual records, not forecasts or health judgments. list and get are read-only, and an explicit --project never changes local project selection.

When Milestones are disabled, reads and mutations return guidance to Project Settings, rather than presenting retained records as an empty project. Re-enabling restores access to retained records and history; members who cannot manage settings should ask a Team Lead. See Configure Sprints and Milestones.

Milestone opening, closing, and eligible deletion belong to browser workflows; there are no CLI lifecycle or delete commands. The CLI has no Sprint entity command family. Task membership belongs to task commands, with independent Sprint and Milestone assignment, clearing, filtering, and explicit planning-history classification. Milestone collection, editing, and browser lifecycle actions are available. Browser task scheduling controls and charts remain separate from these pages.

For example, create from a local Markdown objective and change only its target:

alterac-ai milestone create --title "Public beta" --file milestone-objective.md --target 2026-12-18
alterac-ai milestone list
alterac-ai milestone get 12 --json
alterac-ai milestone update 12 --target 2026-12-21

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 snapshotted task type and its ordered compatible states, durable execution origin, and 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 equivalent structured 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.

The summary allows at most 8,192 characters and the AI hand-off at most 16,384. These limits count Unicode code points: supplementary characters count as one, while combining marks count separately. The API rejects oversized text with field-specific validation errors and saves none of the submission. Shorten the indicated text or file and retry complete with the same work-run GUID; the active run remains available. Content is never silently truncated.

Use an inline value or a file for Markdown input, not both. Required task/Milestone/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 means the command did not fully succeed. Some coordinated metadata operations may already have persisted; inspect the reported task and recovery state, then retry only the failed operation.

Project-scoped commands, including task and Milestone commands, 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.

Retrospective Correction during direct CLI task creation requires a CLI build containing this change. An older installed CLI may reject that choice before contacting the API. Updating only the API/frontend does not update your local CLI. Until a compatible CLI is installed, create the task without that Current target and use the browser to add it as a Correction. Task Builder saved Milestone intent is validated by the deployed API at publication.