CLI Guide

Purpose: help users operate Actspan through the command line with YAML-defined providers, prompts, agents, workflows, policies, and evals.

Start Here

Prerequisites:

an installed actspan command
a workspace file and named target
the selected provider credential for a live run

Run one existing workflow locally before learning the complete command tree:

cd "$HOME/actspan/actspan-examples/openai/data_enrichment"
actspan init workspace.yaml
export OPENAI_API_KEY="<your-openai-api-key>"

actspan run workspace.yaml data_enrichment \
  --input-text "Analyze NVIDIA (NVDA)" \
  --format json

Download and extract the public examples first; adjust the path if you extracted them elsewhere. For a new local workspace, init creates .actspan.env with portal reporting disabled. Export your provider credential in the current shell before live calls, following Configure a local workspace. The key is not written to .actspan.env. Export it again in a new shell.

Expected result: the JSON envelope contains success: true, a run_id, structured output, metrics, and successful workflow steps. run_id identifies the local workflow execution. When portal reporting starts successfully, portal_run_id separately identifies the portal runtime record.

Inspect that run next:

actspan runs
actspan inspect "RUN_ID"

For installation, initialization, validation, and preview, complete the quickstart.

When To Use The CLI

Use the CLI when you want to:

run prompts, agents, and workflows locally
validate and preview a workspace when you need the deeper flow
tune and compare behavior through evals
inspect or automate runs in CI through machine-readable JSON output
collect a joined release evidence package from the portal

Command Lifecycle

The preferred public CLI language is:

actspan init
actspan validate
actspan preview
actspan verify
actspan run
actspan impact
actspan inspect
actspan graph
actspan continue
actspan artifacts
actspan evidence
actspan eval

Compatibility and specialized commands remain available during migration:

actspan setup
actspan preflight
actspan runs
actspan compare
actspan chat
deeper workflow ... subcommands where a conversational or approval flow still needs them

CLI contract details:

Continue After The First Run

Verify configured admission controls without making model calls:

actspan verify workspace.yaml "TARGET" --format text

This tests supported deliberate violations and reports passed, failed, unsupported and unverified checks. It preserves configured warning/blocking mode. Evidence is saved locally and automatically published when connected to the portal. See control verification and automatic evaluation evidence for scope, exit codes and delivery behavior.

Inventory agent dependencies without making provider calls:

actspan impact workspace.yaml
actspan impact workspace.yaml --baseline path/to/baseline-workspace.yaml

The comparison identifies affected targets and their owners, then recommends the eval files already linked to those targets. See dependency inventory and change impact.

1. Run Something First

actspan run "WORKSPACE" "TARGET" --input-text "..."

Use this when you want the shortest path from workspace to value. It executes the selected target directly and records local evidence. Run validate and preview explicitly when they are required checks in your local or CI flow.

2. Inspect Recent History

actspan runs
actspan inspect "RUN_ID"
actspan compare "BASELINE_RUN_ID" "CANDIDATE_RUN_ID"
actspan compare latest_success "CANDIDATE_RUN_ID"
actspan compare --pin-baseline prod_release "RUN_ID"
actspan compare --list-baselines

Use this when you want to inspect recent activity without reading .actspan/ files. Use latest_success when you want the most recent successful run for the same workflow as the baseline. Use baseline:<label> after pinning a reusable baseline label.

3. Initialize The Workspace

actspan init "WORKSPACE"

Use when you need lockfiles, provider/plugin setup, or an initialized workspace directory.

4. Validate Before Running

actspan validate "WORKSPACE"

Use when changing YAML, policies, or pricing assumptions.

5. Preview Without Provider Calls

actspan preview "WORKSPACE" --format json

Use when you want a plan and effective runtime view before execution. Preview does not validate live provider auth, billing, or quota. Missing provider credentials are reported but do not block static preview, including managed resource plans. Add --strict-env to fail on unresolved environment variables. Execution still requires resolved configuration.

6. Run A Target

actspan run "WORKSPACE" "TARGET_NAME" --input-text "..."

If the workspace declares managed provider resources, run compares them with local binding state and provisions or refreshes them before executing the target. Unchanged declarations require no provider resource calls. Preview the workspace first whenever resource declarations or selected documents change.

If you want a live provider readiness check before execution, use:

actspan run "WORKSPACE" "TARGET_NAME" --input-text "..." --provider-check live --no-cache

Older forms such as actspan call ... and actspan workflow invoke ... may still exist in some docs or scripts, but the preferred public language is actspan run ....

For a workflow waiting for user input, continue using its printed run or thread ID:

actspan continue --run-id "PAUSED_RUN_ID" --input-text "..." --format text

Both run and continue show workflow status, identifiers, executed steps, usage, and structured output with readable labels and lists in text mode. For example, a planning result displays numbered milestones and bullet points for risks and first steps. A continuation lists the steps executed in that continuation. Skipped workflow branches are labeled skipped. Use continue --format json when you need the full workflow report, including earlier node outputs and runtime evidence.

7. Evaluate Behavior

actspan eval run "EVAL_YAML"
actspan eval recommend "EVAL_YAML"
actspan eval suggest "RUNS_JSONL"
actspan eval compare "EVAL_YAML" "BASELINE_LOCK_YAML" "CANDIDATE_LOCK_YAML"
actspan eval gate "COMPARE_REPORT_JSON"

8. Download Joined Release Evidence

After a deployment-bound run returns its portal_run_id, collect the exact revision, verification, evaluation, approval, and runtime records through one command:

actspan evidence "WORKSPACE" "WORKFLOW" \
  --environment prod \
  --portal-run-id "PORTAL_RUN_ID" \
  --output .actspan/evidence/release.json

The command verifies the downloaded manifest hash before writing it. This is the shared governance package; use actspan artifacts for local node and tool output files. See revision evidence packages.

Machine-Readable Usage

Use JSON output when integrating with scripts or CI:

--format json
--format cli-json where supported

Contract:

Execution status and automation