CLI Reference

This page lists every operator-facing CLI command shipped by ASF50. Each entry shows the canonical signature, the runtime/state impact, and the human-gate implications.

Read-only by default. Every mutating command is marked. The CLI rejects operations that require write access when only read access is granted.

goal-run.ps1

Run or resume a goal.

Signature

.\scripts\goal-runner\goal-run.ps1 `
  -GoalId <GOAL_ID> `
  [-RuntimeRoot <path>] `
  [-MaxConcurrency 1] `
  [-DryRun] `
  [-StopAtOwnerGate] `
  [-PreferredAdapter <name>] `
  [-PreferredModelClass <class>] `
  [-NoFallback] `
  [-Worktree <path>] `
  [-Branch <name>] `
  [-DispatchWorktree <path>] `
  [-AuditWorktree <path>] `
  [-AuditRepositoryRoot <path>] `
  [-TimeoutSeconds <seconds>]

Purpose

Dispatches the goal one tick. With -DryRun, no agent is invoked. With -StopAtOwnerGate, the run stops at the first open gate.

Read / write

• Read: always reads the contract and the runtime DB.
• Write: writes state transitions, runs, receipts.

Human-gate implications

Stops at any open gate whose scope is in VALID_SCOPES.

Examples

# Dry-run
.\scripts\goal-runner\goal-run.ps1 `
  -GoalId ASF50_DOCS_PORTAL_001 `
  -RuntimeRoot $env:ASF50_RUNTIME_ROOT `
  -DryRun `
  -StopAtOwnerGate

# Live run with bounded concurrency
.\scripts\goal-runner\goal-run.ps1 `
  -GoalId ASF50_DOCS_PORTAL_001 `
  -RuntimeRoot $env:ASF50_RUNTIME_ROOT `
  -MaxConcurrency 1

Expected output

JSON with goal_id, current_state, next_state, next_role, next_task_ids, next_action_path, owner_gate, dry_run, dispatch_executed, diagnostics.

Common failure modes

• Goal Runner error: contract not found — goals/<GOAL_ID>/GOAL_RECORD.yaml missing.
• audit_subject_sha mismatch — the dispatch worktree HEAD does not match the audit target.
• gate not found — a GateId referenced by the contract does not exist.

goal-status.ps1

Print durable state for a goal.

Signature

.\scripts\goal-runner\goal-status.ps1 `
  -GoalId <GOAL_ID> `
  [-RuntimeRoot <path>] `
  [-DispatchWorktree <path>] `
  [-AuditWorktree <path>] `
  [-AuditRepositoryRoot <path>]

Read / write

Read-only.

Example

.\scripts\goal-runner\goal-status.ps1 `
  -GoalId ASF50_DOCS_PORTAL_001 `
  -RuntimeRoot $env:ASF50_RUNTIME_ROOT

goal-pause.ps1

Pause a goal.

.\scripts\goal-runner\goal-pause.ps1 `
  -GoalId <GOAL_ID> `
  [-RuntimeRoot <path>] `
  [-Reason "<text>"]

Read / write: read + write (PAUSED state transition).

goal-resume.ps1

Resume a paused goal.

.\scripts\goal-runner\goal-resume.ps1 `
  -GoalId <GOAL_ID> `
  [-RuntimeRoot <path>]

If the goal was paused during PHASE-00, an PHASE_00_RESUME_APPROVAL gate is required.

goal-cancel.ps1

Cancel a goal.

.\scripts\goal-runner\goal-cancel.ps1 `
  -GoalId <GOAL_ID> `
  [-RuntimeRoot <path>] `
  [-Reason "<text>"]

Cancels to CANCELED. Open gates are released.

goal-recover.ps1

Recover from a known failure mode.

.\scripts\goal-runner\goal-recover.ps1 `
  -GoalId <GOAL_ID> `
  [-RuntimeRoot <path>]

Recovery is goal-type-aware.

goal-doctor.ps1

Detect split-brain runtime.

.\scripts\goal-runner\goal-doctor.ps1 `
  [-RuntimeRoot <path>]

Read-only. Exits non-zero on split-brain.

goal-gate.ps1

Owner-gate decisions.

.\scripts\goal-runner\goal-gate.ps1 `
  -Action list|inspect|approve|reject `
  [-RuntimeRoot <path>] `
  [-GateId <uuid>] `
  [-Approver "<human display name>"] `
  [-Source owner-cli|github-review-approval|signed-ticket] `
  [-Note "<bounded justification>"] `
  [-Reason "<bounded reason>"] `
  [-EvidencePath <path>] `
  [-Scope <scope>]

Read for list/inspect. Write for approve/reject. The CLI rejects sources that are not allowed for the gate's scope.

program-status.ps1

Read-only program-level snapshot.

.\scripts\goal-runner\program-status.ps1 `
  [-GoalId ASF50_PROGRAM_COMPLETION_001] `
  [-Repository <path>] `
  [-RuntimeDb <path>]

Read-only. Opens the SQLite in mode=ro.

ingest-github-review.ps1

Ingest a GitHub review into a gate.

.\scripts\goal-runner\ingest-github-review.ps1 `
  -GoalId <GOAL_ID> `
  -ReviewJsonPath <path>

The review JSON must contain the GitHub login, the state (APPROVED), the PR head SHA, and the review body.

Check scripts

Command	Purpose
scripts/check.ps1	Pre-handoff checks.
scripts/goal-runner/check.ps1	Goal Runner smoke tests.

Python entrypoints

The PowerShell entrypoints are thin wrappers. The underlying Python CLIs are at scripts/goal-runner/*.py. See the source for direct Python invocation.