CLI reference¶

The generated reference below comes from the installed Click commands. For day-to-day coordination, use these groups instead of editing files under .greatminds/ by hand:

Need	Command surface
Create, inspect, move, or annotate tasks	`greatminds task ...`
Send, read, or acknowledge inter-role messages	`greatminds inbox ...`
Acquire, prepare, inspect, or release the singleton stand	`greatminds stand ...`
Converse with a configured role	`greatminds chat ...`
Inspect or control ACP runs	`greatminds run ...`
Inspect transition history	`greatminds journal ...`
Inspect ACP binding state, sessions and process identity	`greatminds agent status [ROLE]`
Watch durable ACP run events	`greatminds run events --follow`
Check stand-gate evidence	`greatminds gate-check <task-id>`
Check blocked-task readiness	`greatminds wake-check`
Check stale agents, stale tasks, and orphaned intents	`greatminds watchdog`
Launch, restart, or update a fleet	`greatminds launch`, `greatminds daemon restart`, `greatminds update`
Inspect project docs and runtime paths	`greatminds project ...`, `greatminds task paths`

greatminds¶

Local ACP agent orchestration, operator conversations and task workflows.

Usage:

greatminds [OPTIONS] COMMAND [ARGS]...

Options:

  --version   Show the version and exit.
  -h, --help  Show this message and exit.

greatminds agent¶

Inspect configured ACP agents and their actual runs.

Usage:

greatminds agent [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds agent status¶

Show configured bindings, active runs and latest terminal outcomes.

Usage:

greatminds agent status [OPTIONS] [ROLES]...

Options:

  --project-dir DIRECTORY
  --json
  -h, --help               Show this message and exit.

greatminds agent tools¶

List configured ACP manifests; configuration is not live compatibility proof.

Usage:

greatminds agent tools [OPTIONS]

Options:

  --project-dir DIRECTORY
  --json
  -h, --help               Show this message and exit.

greatminds chat¶

Queue user messages and attach to daemon-owned ACP conversations.

Usage:

greatminds chat [OPTIONS] COMMAND [ARGS]...

Options:

  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds chat attach¶

Read output/events without starting, cancelling, or resending a turn.

Usage:

greatminds chat attach [OPTIONS] CONVERSATION_ID

Options:

  --after INTEGER RANGE  Last received event cursor.  [x>=0]
  --follow               Stream JSON pages until Ctrl-C; detaching leaves the
                         turn running.
  --text                 Render readable messages instead of JSON pages.
  -h, --help             Show this message and exit.

greatminds chat bindings¶

List configured role bindings for interactive clients, without launching agents.

Usage:

greatminds chat bindings [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds chat close¶

Stop admission and ask the daemon to cancel work and release the session.

Usage:

greatminds chat close [OPTIONS] CONVERSATION_ID

Options:

  -h, --help  Show this message and exit.

greatminds chat create¶

Create a conversation pinned to an existing role binding.

Usage:

greatminds chat create [OPTIONS] BINDING_ID

Options:

  --task TEXT  Pin an exact workflow task ID and its current revision.
  -h, --help   Show this message and exit.

greatminds chat interrupt¶

Cancel a queued message or request cancellation of its active ACP turn.

Usage:

greatminds chat interrupt [OPTIONS] CONVERSATION_ID REQUEST_ID

Options:

  -h, --help  Show this message and exit.

greatminds chat list¶

List conversation metadata; prompt text and provider output are excluded.

Usage:

greatminds chat list [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds chat send¶

Queue one message; the running coordd process executes it.

Usage:

greatminds chat send [OPTIONS] CONVERSATION_ID

Options:

  --message TEXT     [required]
  --request-id TEXT  Reuse this ID when retrying the same delivery.
  -h, --help         Show this message and exit.

greatminds chat talk¶

Read responses, send messages, and answer one-time permissions in a terminal.

Usage:

greatminds chat talk [OPTIONS] CONVERSATION_ID

Options:

  --after INTEGER RANGE  [x>=0]
  -h, --help             Show this message and exit.

greatminds check-git-permission¶

greatminds check-git-permission — gate git commit / git push by role.

Installed by greatminds setup as a pre-commit hook. Reads schema.yaml git_permissions and refuses if $GREATMINDS_ROLE is not in the allowed list for the given verb.

Usage::

greatminds check-git-permission commit
greatminds check-git-permission push

Exit codes: 0 allowed (or GREATMINDS_ROLE is in git_permissions.) 2 $GREATMINDS_ROLE unset or not allowed for this verb 3 schema lookup failed (missing section or unreadable file)

Task 0091 item 2.

Usage:

greatminds check-git-permission [OPTIONS] {commit|push}

Options:

  -h, --help  Show this message and exit.

greatminds coordd¶

run the ACP execution daemon

Usage:

greatminds coordd [OPTIONS]

Options:

  --project-dir DIRECTORY
  --project TEXT              Project name registered by greatminds daemon
                              install.
  --interval-sec FLOAT RANGE  [x>=0.2]
  -v, --verbose
  --foreground                Run in this terminal instead of starting an
                              independent daemon.
  --once                      Reconcile and execute one dispatch batch, then
                              exit.
  -h, --help                  Show this message and exit.

greatminds daemon¶

Manage independent per-project background daemons.

start/stop/restart/status use the same project lifecycle as the web interface. No installation or systemd is required. Optional install and --systemd commands integrate with a user service manager for login startup and restart.

Usage:

greatminds daemon [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds daemon doctor¶

Check declared ACP prerequisites; does not verify login or protocol support.

Usage:

greatminds daemon doctor [OPTIONS]

Options:

  --project TEXT           project name (default: registry or project
                           directory name)
  --project-dir DIRECTORY  project root (default: cwd)
  --json                   Machine-readable static checks
  -h, --help               Show this message and exit.

greatminds daemon install¶

install template unit + register project

Usage:

greatminds daemon install [OPTIONS]

Options:

  --name TEXT              project name (default: registry or project
                           directory name)
  --project-dir DIRECTORY  project root (default: cwd)
  -h, --help               Show this message and exit.

greatminds daemon list¶

list all registered projects + active state

Usage:

greatminds daemon list [OPTIONS]

Options:

  --systemd   Inspect optional installed user services.
  -h, --help  Show this message and exit.

greatminds daemon repair¶

Idempotently enable the project's daemon instance.

Usage:

greatminds daemon repair [OPTIONS]

Options:

  --name TEXT              project name (default: registry or project
                           directory name)
  --project-dir DIRECTORY  project root (default: cwd)
  -h, --help               Show this message and exit.

greatminds daemon restart¶

restart the daemon for a project

Usage:

greatminds daemon restart [OPTIONS]

Options:

  --project TEXT           project name (default: registry or project
                           directory name)
  --project-dir DIRECTORY  project root (default: cwd)
  --systemd                Use the optional installed systemd user service.
  -h, --help               Show this message and exit.

greatminds daemon start¶

start the daemon for a project

Usage:

greatminds daemon start [OPTIONS]

Options:

  --project TEXT           project name (default: registry or project
                           directory name)
  --project-dir DIRECTORY  project root (default: cwd)
  --systemd                Use the optional installed systemd user service.
  -h, --help               Show this message and exit.

greatminds daemon status¶

show daemon status for a project

Usage:

greatminds daemon status [OPTIONS]

Options:

  --project TEXT           project name (default: registry or project
                           directory name)
  --project-dir DIRECTORY  project root (default: cwd)
  --systemd                Inspect the optional installed systemd user
                           service.
  -h, --help               Show this message and exit.

greatminds daemon stop¶

stop the daemon for a project

Usage:

greatminds daemon stop [OPTIONS]

Options:

  --project TEXT           project name (default: registry or project
                           directory name)
  --project-dir DIRECTORY  project root (default: cwd)
  --systemd                Use the optional installed systemd user service.
  -h, --help               Show this message and exit.

greatminds dashboard¶

show ACP runs, assignments and holds

Usage:

greatminds dashboard [OPTIONS]

Options:

  --project-dir DIRECTORY
  --interval FLOAT RANGE   [x>=0.2]
  --once
  --json
  -h, --help               Show this message and exit.

greatminds gate-check¶

Check stand-evidence gate for a product task.

Usage: greatminds gate-check [--project-dir

] [--canon-dir ]

may be the full id (for example TASK-slug) or just the seq.

Looks up the task across coordination queues, reads its plan block, and verifies stand-evidence per the schema: - plan.stand_required: false → output 'n/a' - plan.stand_required: true → require the latest tests block to carry lease-backed stand evidence for the task commit and an acceptable result.

Exit code: 0 pass | n/a 1 fail 2 missing 3 error (task not found, malformed)

Usage:

greatminds gate-check [OPTIONS] TASK_ID

Options:

  --project-dir DIRECTORY  project root (default: cwd)
  --canon-dir DIRECTORY    canon data dir (default: packaged greatminds.data)
  -v, --verbose            print diagnostic reasons
  -h, --help               Show this message and exit.

greatminds inbox¶

inter-role inbox messaging (wake/ask/info)

Usage:

greatminds inbox [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds inbox ack¶

Usage:

greatminds inbox ack [OPTIONS] PATH

Options:

  -h, --help  Show this message and exit.

greatminds inbox list¶

Usage:

greatminds inbox list [OPTIONS] [ROLE]

Options:

  -h, --help  Show this message and exit.

greatminds inbox send¶

Usage:

greatminds inbox send [OPTIONS] TO

Options:

  --kind TEXT  message kind (schema.inbox.allowed_kinds)  [required]
  --task TEXT  task id ref
  --body TEXT  literal | @file | - (stdin)
  -h, --help   Show this message and exit.

greatminds inbox show¶

Usage:

greatminds inbox show [OPTIONS] PATH

Options:

  -h, --help  Show this message and exit.

greatminds intent-clean¶

intent-clean — remove orphan intent files whose task has already moved.

An intent file says "I'm about to mv from to ". After the mv, the agent is supposed to delete its intent. If an agent crashes mid-tick, its intent file is left behind. This command garbage- collects them: if the task is no longer in the intent's from queue, the mv has completed (or the task was withdrawn) and the intent is stale.

Safety: only removes intents older than --min-age-sec (default 300). Recently-created intents may be legitimate ongoing claims.

Usage:

greatminds intent-clean [OPTIONS]

Options:

  --project-dir DIRECTORY  project root (default: cwd)
  --min-age-sec INTEGER    only consider intents older than this; default 300s
  --dry-run                report what would be removed; don't delete
  --quiet                  suppress summary line on no-ops
  -h, --help               Show this message and exit.

greatminds journal¶

greatminds journal — read-only view of the coordination journal.

greatminds journal tail provides a clean, read-only view with -n/--role/--task filters. It never writes.

Each journal line is a JSON object::

{"t": <iso>, "actor"|"role": <ROLE>, "task": <id>,
 "from": <q>, "to": <q>, "reason": <str>, "intent_id": <str>}

Usage:

greatminds journal [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds journal tail¶

Print the last -n journal entries (read-only), optionally filtered by --role and/or --task.

Usage:

greatminds journal tail [OPTIONS]

Options:

  -n, --num INTEGER        show the last N matching entries (default 20)
  --role TEXT              only entries by this acting role
  --task TEXT              only entries for this task (short id / full id)
  --project-dir DIRECTORY  project root containing coordination/ (default:
                           cwd)
  -h, --help               Show this message and exit.

greatminds launch¶

open ACP daemon and operator frontends

Usage:

greatminds launch [OPTIONS]

Options:

  --target [tmux|vscode|cursor-ide]
  --project-dir DIRECTORY
  --venv DIRECTORY                Python environment containing Greatminds;
                                  defaults to the current interpreter.
  -h, --help                      Show this message and exit.

greatminds lint-tokens¶

Lint usage across the canon coordination files.

Scans COORDINATE.md, root *.md, templates/, plugin skills and mcp configs for <TOKEN> patterns. Compares with the token catalog in PROJECT_VARIABLES.md.

Exits non-zero if unknown tokens are found. Unused catalog tokens are warned about but do not fail.

Usage:

greatminds lint-tokens [OPTIONS]

Options:

  --canon-dir DIRECTORY  canon data dir (default: packaged greatminds.data)
  -h, --help             Show this message and exit.

greatminds migrate-stand-history¶

Archive coordination/stand_done/* under coordination/archive/stand-history/.

Usage:

greatminds migrate-stand-history [OPTIONS]

Options:

  --coord TEXT  path to coordination/ (default: resolved via env / cwd)
  --dry-run     report what would move; touch nothing
  -h, --help    Show this message and exit.

greatminds migrate-task¶

greatminds migrate-task — convert markdown task files to strict .yaml.

Input format: a markdown file with multiple YAML blocks separated by ---, optionally interleaved with free prose. * the first dict-shaped YAML block is the header (id, stream, kind, ...); * subsequent dict-shaped YAML blocks whose only top-level key is a known "_block" name are progress blocks; * everything else (prose, headings) becomes the task's description field.

New format: single YAML file with header fields at top level and an ordered blocks: list. See greatminds task show output and the packaged schema for the exact shape.

Usage: greatminds migrate-task --file path/to/task.md one file greatminds migrate-task --queue feature_dev all active in a queue greatminds migrate-task --all every .md task in .greatminds/ (active queues only by default; pass --include-terminal to also touch verified/, archive/, etc.)

Flags: --dry-run report what would be migrated; write nothing --keep-md leave .md alongside new .yaml --force overwrite existing .yaml if present

Best-effort: per-block fields are remapped where the canonical name changed (written_by→by, written_at→at, closed_by→by, closed_at→at). Unknown fields are preserved verbatim under their original key.

Usage:

greatminds migrate-task [OPTIONS]

Options:

  --file TEXT         single .md file to migrate
  --queue TEXT        migrate all .md in this queue
  --all               migrate every .md in active queues
  --include-terminal  with --all, also include verified/archive/stand_done/...
  --dry-run
  --keep-md           leave the original .md file in place
  --force             overwrite existing .yaml
  -h, --help          Show this message and exit.

greatminds plan¶

plan — ARCHITECT-PLANNER convenience: triage + plan + route in one go.

Atomic 4-step chain:

append-block triage on the inbox task
mv → feature_plan
append-block plan (with all required fields)
mv → per-scope queue (or feature_docs_review for --audit-only)

The chain stops at the first failing step and prints exactly where it stopped and what to do — never a silent partial failure.

Only ARCHITECT-PLANNER may run this command (the GREATMINDS_ROLE env var is enforced; refusing other roles up-front avoids ambiguity).

Usage:

greatminds plan [OPTIONS] ID

Options:

  --scope [backend|docs|ui]      [required]
  --assignee-role TEXT           [required]
  --base-commit TEXT             [required]
  --plan-kind [full|bugfix]      [required]
  --mode [A|B|C]                 [required]
  --stand-required [true|false]  [required]
  --stand-reason TEXT
  --body TEXT                    plan text (literal)
  --body-file TEXT               plan text: file path, or - for stdin
  --triage TEXT                  optional triage note
  --stop-at [plan]               stop after plan block; do not route to per-
                                 scope queue
  --audit-only                   READER audit (scope must be docs): no WRITER
                                 step — route straight to feature_docs_review.
  -h, --help                     Show this message and exit.

greatminds project¶

project documentation, effective contracts and execution presets.

Usage:

greatminds project [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds project execution¶

validate and show the ACP execution contract (read-only).

Usage:

greatminds project execution [OPTIONS]

Options:

  --config FILE  defaults to coordination/execution.yaml in the current
                 project.
  -h, --help     Show this message and exit.

greatminds project preset¶

preview or explicitly apply a role roster to an existing ACP manifest.

Usage:

greatminds project preset [OPTIONS] {local|ui|docs|deployed|full}

Options:

  --agent TEXT             Existing agent manifest ID to use for the selected
                           roles.  [required]
  --project-dir DIRECTORY
  --apply                  Atomically write the previewed bindings; preserve
                           existing custom bindings.
  -h, --help               Show this message and exit.

greatminds project presets¶

list available ACP role rosters without changing the project.

Usage:

greatminds project presets [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds project schema¶

print the effective schema, not the project mirror.

Usage:

greatminds project schema [OPTIONS]

Options:

  --project-dir DIRECTORY  project whose generated schema copy should be
                           inspected.
  --json                   include schema identity, document, and project-copy
                           status.
  --check                  check the project mirror; exit 2 on drift, missing,
                           or unreadable copy.
  -h, --help               Show this message and exit.

greatminds project show¶

print coordination/PROJECT.md (read-only).

Usage:

greatminds project show [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds report-upstream¶

greatminds report-upstream — file a bug against the upstream greatminds repo.

Three submission modes, configurable via --mode or coord.yaml: report.mode:

url Default. URL-encode the body into https://github.com/<repo>/issues/new?... and open it in the user's browser (also printed to stdout). Zero creds, zero side effects beyond a browser tab. gh Shell out to the local gh CLI (gh issue create); requires gh auth login already done. api-token POST to the GitHub REST API directly, using a PAT read from $<token_env> first, then .greatminds/PROJECT.env. No token is bundled in the PyPI artifact.

Designed for MAINTAINER use only — other roles file inbox/maintainer/ asks; MAINTAINER triages "our bug vs upstream" and invokes this command when the bug is upstream.

Usage:

greatminds report-upstream [OPTIONS]

Options:

  --title TEXT                  issue title (short)  [required]
  --body TEXT                   issue body text (inline)
  --body-file FILE              read body from FILE (use '-' for stdin)
  --severity [low|normal|high]  [default: normal]
  --label TEXT                  label to attach (repeatable)
  --mode [url|gh|api-token]     submission mode (overrides coord.yaml
                                report.mode)
  --dry-run                     print the assembled body to stdout and exit
  --no-diagnostics              skip auto-collected diagnostics (manual body
                                only)
  --project-dir DIRECTORY       override project root (default: cwd /
                                coord.yaml)
  -h, --help                    Show this message and exit.

greatminds run¶

Inspect and control daemon-owned ACP execution.

Usage:

greatminds run [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds run account-resume¶

Resolve the inspected account hold; do not retry any task or change identity.

Usage:

greatminds run account-resume [OPTIONS] ACCOUNT

Options:

  --hold-id TEXT  [required]
  --reason TEXT   [required]
  -h, --help      Show this message and exit.

greatminds run cancel¶

Request bounded cancellation by the ACP daemon.

Usage:

greatminds run cancel [OPTIONS] RUN_ID

Options:

  -h, --help  Show this message and exit.

greatminds run command¶

Request a configured command from the daemon; optionally wait for its receipt.

Usage:

greatminds run command [OPTIONS] COMMAND_ID

Options:

  --request-id TEXT
  --wait FLOAT RANGE            [x>=0]
  --output-limit INTEGER RANGE  [0<=x<=65536]
  -h, --help                    Show this message and exit.

greatminds run command-resolve¶

Acknowledge an uncertain command after inspection; grant no passing evidence.

Usage:

greatminds run command-resolve [OPTIONS] REQUEST_ID

Options:

  --reason TEXT  [required]
  -h, --help     Show this message and exit.

greatminds run command-status¶

Inspect an executed command and its output artifact paths.

Usage:

greatminds run command-status [OPTIONS] REQUEST_ID

Options:

  --output-limit INTEGER RANGE  [0<=x<=65536]
  -h, --help                    Show this message and exit.

greatminds run contract¶

Read the assigned context or frozen schema using the run credential.

Usage:

greatminds run contract [OPTIONS]

Options:

  --schema    Show this run's pinned schema instead of its assigned context
  -h, --help  Show this message and exit.

greatminds run doctor¶

Aggregate local configuration, run, dependency and recovery findings.

Usage:

greatminds run doctor [OPTIONS]

Options:

  --project-dir DIRECTORY
  --json
  --bundle FILE            Write a private local diagnostic JSON file; never
                           overwrite an existing path.
  -h, --help               Show this message and exit.

greatminds run events¶

Read the durable ACP event stream without launching an executor.

Usage:

greatminds run events [OPTIONS]

Options:

  --project-dir DIRECTORY
  --after INTEGER RANGE    Exclusive event sequence cursor.  [x>=0]
  --limit INTEGER RANGE    [1<=x<=10000]
  --follow                 Continue emitting new events as JSON Lines.
  --interval FLOAT RANGE   [x>=0.2]
  -h, --help               Show this message and exit.

greatminds run pause¶

Pause new ACP dispatch; existing runs can finish.

Usage:

greatminds run pause [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds run permission¶

Inspect a permission request, or answer it for the live ACP callback.

Usage:

greatminds run permission [OPTIONS] REQUEST_ID

Options:

  --option TEXT  Choose an option ID from this exact live request
  -h, --help     Show this message and exit.

greatminds run repair¶

Request bounded reconciliation of an incomplete system operation.

Usage:

greatminds run repair [OPTIONS]

Options:

  --operation TEXT  [required]
  --abandon         cancel an uncommitted intent after inspection
  --reason TEXT     required when abandoning an intent
  -h, --help        Show this message and exit.

greatminds run resume¶

Resume ACP dispatch.

Usage:

greatminds run resume [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds run retry¶

Authorize another attempt after a terminal or waiting run.

Usage:

greatminds run retry [OPTIONS] RUN_ID

Options:

  -h, --help  Show this message and exit.

greatminds run status¶

Print the versioned run snapshot and assignment reasons as JSON.

Usage:

greatminds run status [OPTIONS]

Options:

  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds run submit¶

Receive a typed result using the assigned run's environment credential.

Usage:

greatminds run submit [OPTIONS]

Options:

  --file FILE
  --json TEXT  Submit a JSON decision directly without creating a file
  -h, --help   Show this message and exit.

greatminds setup¶

initialize an ACP project

Usage:

greatminds setup [OPTIONS]

Options:

  --project-dir DIRECTORY
  --execution-config FILE  Explicit ACP manifests and role bindings; otherwise
                           create an empty contract.
  -h, --help               Show this message and exit.

greatminds stand¶

singleton stand lease and deployment commands

Usage:

greatminds stand [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds stand deploy¶

Run the active lease's deploy profile and transition ready/down.

Coordd runs this automatically for a preparing lease; this command is the manual/operator entry to the same deploy engine.

Usage:

greatminds stand deploy [OPTIONS]

Options:

  --lease-id TEXT               active lease to deploy (must match state.yaml)
                                [required]
  --timeout FLOAT               kill the playbook after N seconds (rc=124)
  --output-limit INTEGER RANGE  maximum captured bytes per output stream
                                [default: 1048576; 1<=x<=67108864]
  -h, --help                    Show this message and exit.

greatminds stand deployment-recover¶

Stop a tracked orphan process group; preserve its uncertain outcome.

Usage:

greatminds stand deployment-recover [OPTIONS] ATTEMPT_ID

Options:

  -h, --help  Show this message and exit.

greatminds stand deployment-resolve¶

Acknowledge a cleaned attempt; does not deploy or mark the stand ready.

Usage:

greatminds stand deployment-resolve [OPTIONS] ATTEMPT_ID

Options:

  --reason TEXT  operator assessment of external effects and recovery
                 [required]
  -h, --help     Show this message and exit.

greatminds stand deployment-status¶

Inspect durable external deployment attempts and unresolved outcomes.

Usage:

greatminds stand deployment-status [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds stand down¶

Mark the stand down after a deploy or infrastructure incident.

MAINTAINER-only.

Usage:

greatminds stand down [OPTIONS]

Options:

  --reason TEXT  operational reason logged in state file  [required]
  -h, --help     Show this message and exit.

greatminds stand lease¶

Request a lease on the singleton stand.

Behavior: - On state=free: transitions free→preparing(lease_id); SK picks up the new lease on its next tick. - On state≠free: enqueues the request; the lease becomes active when SK releases the current one.

Returns the freshly-minted lease_id (UUID4) as the LAST line of stdout. Callers (test scripts, agents) capture this token; only the holder may release.

Usage:

greatminds stand lease [OPTIONS]

Options:

  --task TEXT                  product-task id this lease serves  [required]
  --worktree TEXT              path to the worktree coordd will deploy from.
                               Optional: defaults to the canonical per-task
                               worktree (.worktrees/<task_id>) and is auto-
                               created if absent, so review_session leases
                               (EXPLORER) need no raw git.
  --profile TEXT               registered deploy profile name from stand-
                               profiles.yaml  [required]
  --ttl-seconds INTEGER        override ttl (default: schema
                               lease.ttl_seconds_default)
  --deploy-prerequisites-only  run only prerequisite-tagged profile tasks
                               before the holder performs the actual deploy.
                               Overrides the profile-level setting.
  --profile-approval TEXT      explicit approval marker required by high-risk
                               profiles
  -h, --help                   Show this message and exit.

greatminds stand profiles¶

inspect and validate stand profile registry

Usage:

greatminds stand profiles [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds stand profiles doctor¶

Validate registry tokens and referenced YAML playbooks.

Usage:

greatminds stand profiles doctor [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds stand profiles list¶

List registered stand profiles for this project.

Usage:

greatminds stand profiles list [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds stand ready¶

Transition a prepared lease to ready and notify the holder.

Requires fresh managed deployment evidence in ACP projects. Legacy projects retain the deploy marker check until configuration migration.

Usage:

greatminds stand ready [OPTIONS]

Options:

  --lease-id TEXT  lease that just finished preparing  [required]
  -h, --help       Show this message and exit.

greatminds stand reclaim¶

Reclaim an expired lease whose holder is no longer alive.

A stale lease (a crashed holder past its ttl_seconds) otherwise permanently locks the singleton — release is holder-only and there was no reaper. reclaim is restricted to STAND-KEEPER / ARCHITECT-PLANNER (the stand owners) and MAINTAINER (whose contract carries reclaim_stale_stand_lease_past_ttl_with_dead_holder as a recovery duty); it refuses to clobber a live, in-TTL lease OR a lease whose holder pid is still alive: it only frees a lease that is BOTH past its TTL AND held by a dead/absent agent.

Usage:

greatminds stand reclaim [OPTIONS]

Options:

  --lease-id TEXT  lease to reclaim (default: the active lease)
  -h, --help       Show this message and exit.

greatminds stand release¶

Release the active lease and promote the next queued lease.

Only the holder may release. The CLI rejects with exit_code=3 if --lease-id doesn't match the current active lease. Result is a CLOSED ENUM (pass/fail/partial) — no prose channel; TESTER's observations live exclusively in the product-task's tests block.

If the holder mismatches but the lease_id is in the queue, the requester is cancelling a pending request (state file removes the queue entry; no state transition).

Usage:

greatminds stand release [OPTIONS]

Options:

  --lease-id TEXT               lease_id token returned by `stand lease`
                                [required]
  --result [pass|fail|partial]  machine-readable resolution status (NOT a
                                report)  [required]
  -h, --help                    Show this message and exit.

greatminds stand status¶

Print the singleton stand resource state.

Reads .greatminds/.stand/state.yaml (creates a synthetic empty-state view when the file doesn't exist yet) and prints a compact human-readable summary: state, active lease (if any), queue contents, and the last few transitions.

Read-only. Use stand lease, stand ready, stand release, stand down, and stand up for mutations.

Usage:

greatminds stand status [OPTIONS]

Options:

  -h, --help  Show this message and exit.

greatminds stand up¶

Recover a down stand and resume queue processing.

MAINTAINER-only.

Usage:

greatminds stand up [OPTIONS]

Options:

  --reason TEXT  resolution note  [required]
  -h, --help     Show this message and exit.

greatminds task¶

task-file CRUD (intake, mv, append-block, show, list, validate)

Usage:

greatminds task [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds task append-block¶

Usage:

greatminds task append-block [OPTIONS] {blocked|implementation|plan|reader_rev
                             iew|review|rollback|session_iteration|tests|triag
                             e}

Options:

  --id TEXT         [required]
  --field TEXT      key=value (repeat)
  --body TEXT       block body: literal text | @PATH (read file) | - (stdin)
  --body-file TEXT  block body file path (alias for --body @PATH; preserved
                    for orchestrator and old-CLI compat)
  -h, --help        Show this message and exit.

greatminds task list¶

Usage:

greatminds task list [OPTIONS] QUEUE

Options:

  --json      emit a machine-readable JSON array (id/title/queue/file).
  -h, --help  Show this message and exit.

greatminds task mv¶

Usage:

greatminds task mv [OPTIONS] ID TO_QUEUE

Options:

  --reason TEXT
  -h, --help     Show this message and exit.

greatminds task new¶

Usage:

greatminds task new [OPTIONS]

Options:

  --stream [product|review_session]
                                  [required]
  --title TEXT                    [required]
  --reporter TEXT
  --priority [high|low|normal]
  --kind TEXT                     product:
                                  bugfix|docs|feature|ops|release|research
  --scope TEXT                    product:
                                  backend|docs|release|research|stand|ui
  --hosts TEXT                    list of hosts; repeat the flag or comma-
                                  separate values
  --evidence-for TEXT             task ids this run is evidence for; repeat or
                                  comma-separate
  --mode [A|B|C]
  --target-functionality TEXT
  --scenarios TEXT                scenario IDs; repeat or comma-separate
  --description TEXT              literal | @file | - (stdin)
  --in-queue TEXT                 destination queue (default depends on
                                  stream)
  --seq TEXT                      override numeric id prefix
  --reason TEXT                   journal reason
  -h, --help                      Show this message and exit.

greatminds task paths¶

Usage:

greatminds task paths [OPTIONS] [ID]

Options:

  -h, --help  Show this message and exit.

greatminds task show¶

Usage:

greatminds task show [OPTIONS] ID

Options:

  -h, --help  Show this message and exit.

greatminds task validate¶

Usage:

greatminds task validate [OPTIONS] ID

Options:

  --id TEXT    (back-compat) task id — same as the positional ID
  --file TEXT  explicit path to a .yaml task file
  -h, --help   Show this message and exit.

greatminds task withdraw¶

Usage:

greatminds task withdraw [OPTIONS] ID

Options:

  --reason TEXT  why the task is being withdrawn / cancelled  [required]
  -h, --help     Show this message and exit.

greatminds update¶

Upgrade Greatminds and refresh the current ACP project.

Installed services are refreshed with try-restart, which preserves inactive services. Updating never installs a service or starts a native agent frontend. Use --post-pip to repeat project refresh without installing the package.

Usage:

greatminds update [OPTIONS]

Options:

  --post-pip      skip package installation; refresh project and installed
                  services.
  --check         report what would change; no actions.
  --dry-run       alias of --check.
  --major         allow major-version bump (default: refuse).
  --project TEXT  registered project name (default: current project).
  -h, --help      Show this message and exit.

greatminds wake-check¶

Inspect dependency and task-readiness gates used by the daemon.

Reports ready tasks, missing or impossible dependencies, cycles, live-role holds and pending operations through the shared maintenance service. Inspection never moves tasks or starts agents. The daemon applies authorized system resumes.

Usage:

greatminds wake-check [OPTIONS]

Options:

  --project-dir DIRECTORY  project root containing .greatminds/ (default: cwd)
  --canon-dir DIRECTORY    canon data dir (default: packaged greatminds.data)
  --quiet                  suppress no-findings output
  --json                   versioned dependency/controller findings
  -h, --help               Show this message and exit.

greatminds watchdog¶

Read-only watchdog for the coordination filesystem.

Reports: - orphaned intent files older than schema.watchdog.intent_orphan_seconds - tasks in active queues older than task_stale_in_active_queue_seconds - tasks in review queues older than task_stale_in_review_queue_seconds - ACP runs waiting for authentication/input, failed, or missing their process

This operator inspection never moves files, alters state, or requires an LLM turn.

Exit code: 0 for inspection findings; nonzero for project/schema errors. --quiet only prints sections with findings.

Usage:

greatminds watchdog [OPTIONS]

Options:

  --project-dir DIRECTORY  project root containing .greatminds/ (default: cwd)
  --canon-dir DIRECTORY    canon data directory (default: packaged
                           greatminds.data)
  --quiet                  only print sections with findings
  -h, --help               Show this message and exit.

greatminds web¶

Run the local web workspace without application authentication.

Usage:

greatminds web [OPTIONS]

Options:

  --project-dir DIRECTORY
  --host TEXT              [default: 127.0.0.1]
  --port INTEGER RANGE     HTTP port; 0 selects a free port.  [default: 8765;
                           0<=x<=65535]
  --daemon / --no-daemon   Start coordd if no project daemon is running.
                           [default: daemon]
  -h, --help               Show this message and exit.

greatminds worktree¶

per-task git worktree lifecycle.

Usage:

greatminds worktree [OPTIONS] COMMAND [ARGS]...

Options:

  -h, --help  Show this message and exit.

greatminds worktree assert-drained¶

Exit non-zero if any feature_* queue is non-empty.

Deploying the worktree feature on top of a non-drained pipeline can produce unmergeable state. MAINTAINER runs this before rebuilding the wheel; non-zero refuses the run with the list of in-flight tasks per queue.

Usage:

greatminds worktree assert-drained [OPTIONS]

Options:

  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree create¶

Create a worktree for TASK_ID (idempotent).

Usage:

greatminds worktree create [OPTIONS] TASK_ID

Options:

  --base TEXT              Override base commit (default: task's
                           plan.base_commit, then main HEAD).
  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree list¶

List active worktrees.

Usage:

greatminds worktree list [OPTIONS]

Options:

  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree merge¶

Merge task/TASK_ID into main with the policy strategy.

Usage:

greatminds worktree merge [OPTIONS] TASK_ID

Options:

  --summary TEXT           Commit message suffix.
  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree path¶

Print the worktree path for TASK_ID.

Self-contained substitute for $GREATMINDS_TASK_WORKTREE: an implementer agent or STAND-KEEPER's rsync wrapper invokes cd "$(greatminds worktree path <task-id>)" to enter the task's isolated tree.

Usage:

greatminds worktree path [OPTIONS] TASK_ID

Options:

  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree prune¶

Remove worktrees whose task_id is not in any active queue.

Usage:

greatminds worktree prune [OPTIONS]

Options:

  --project-dir DIRECTORY
  -h, --help               Show this message and exit.

greatminds worktree remove¶

Remove the worktree for TASK_ID.

Usage:

greatminds worktree remove [OPTIONS] TASK_ID

Options:

  --force
  --project-dir DIRECTORY
  -h, --help               Show this message and exit.