charter-cli

Command-line interface for Charter. Install this package when you want the charter command for project setup, workflow installation, execution, and run inspection from the terminal.

pip install charter-cli
charter --help

For the workflow model, config files, and shared examples, see the main Charter README.

Use This Package When

• You want to bootstrap and operate Charter projects from the terminal.
• You want Charter to resolve capabilities from project config, workflow plans, and installed integrations.
• You want local interactive handling for gates and input steps when running in a TTY.

What charter-cli Owns

• project discovery and charter.yml loading
• workflow pulling and project-runtime dependency installation into .charter/.venv
• capability resolution precedence for charter run
• subprocess integration lifecycle for command-backed capabilities
• interactive terminal UX for gate and input pauses
• run inspection commands such as status and runs list

Command Reference

charter init [PATH]
charter pull [--project-path PATH]
charter install [--project-path PATH]
charter workflows list [--json] [--project-path PATH]
charter workflows show WORKFLOW_ID [--project-path PATH]
charter run WORKFLOW_ID [options]
charter resume RUN_ID (--approve | --deny) [options]
charter submit-input RUN_ID --answers JSON_OBJECT [options]
charter status RUN_ID [--project-path PATH]
charter runs list [--limit N] [--cursor TOKEN] [--project-path PATH]

Workflow ids come from manifest.yml. They must start with a letter or number and may contain only letters, numbers, ., _, or -. Workflows use workflows/<workflow-id>/plan.yml with a sibling workflows/<workflow-id>/manifest.yml.

Common Flows

Initial project setup:

charter init
charter pull
charter install

charter install is required before project-backed execution commands such as run, resume, and submit-input. The host-installed CLI activates .charter/.venv for project-installed integrations and project-local Python dependencies instead of delegating to a second project-local Charter CLI.

Run a workflow with variables:

charter run research-summary \
  --var topic="quantum computing"

When manifest.yml declares required inputs and the CLI is attached to a terminal, charter run prompts for any missing required values before the run starts. Non-interactive callers should pass those values with --var.

Override capability resolution explicitly for a run:

charter run pipeline \
  --capability binding/extractor="./extractor.py" \
  --capability binding/transformer="./transformer.py"

Discover workflows for agents or tooling:

charter workflows list --json
charter workflows show research-summary

charter workflows show prints a man-page-style command contract for one workflow: synopsis, declared inputs, capability role descriptions, current project binding status, workflow files, examples, and next commands. It does not require charter install because it only inspects project and workflow metadata.

Resume paused work:

charter resume <run_id> --approve
charter resume <run_id> --deny --note "Needs another pass"
charter submit-input <run_id> --answers '{"color":"blue","notes":"ship it"}'

Input steps use the canonical questions: / outputs: YAML form with optional show context. The CLI pause help lists every question id and kind, and --answers must be a JSON object keyed by those question ids.

Inspect run state:

charter status <run_id>
charter runs list
charter runs list --limit 25
charter runs list --limit 25 --cursor <token-from-previous-page>

Runtime commands keep output compact and diagnostic-first. charter workflows show is the contract-shaped inspection surface; run, resume, submit-input, and status report the current result plainly, including failed step context and available stderr/provider error text without wrapping workflow outputs in metadata.

Integration Resolution

For every explicit uses: reference in a workflow step, charter run resolves it in this order:

1. --capability <uses-ref>=SPEC
2. workflow plan.yml bindings over root charter.yml capabilities
3. direct root charter.yml capabilities

SPEC can be either:

• module.path:ClassName for an in-process Python integration
• a shell command string for a subprocess-backed integration

Resolved capability metadata is persisted with the run so a normal resume or submit-input does not need the original overrides again.

Workflow manifests only define the workflow contract. Workflow plans may use bindings: role descriptions and shallow with: config overlays, but they do not define capability implementations or Python package dependencies. Steps use uses: binding/<id> for plan-local bindings and uses: capability/<id> for direct project capabilities.

Both uses: integrations, optional secrets backends, and optional storage backends are discovered from installed Python packages via entry points. Source code sitting next to a project is not enough on its own; the relevant package must be installed in the active runtime environment.

Related Packages

• charter-core: internal runtime engine used by the CLI
• charter-integration-sdk: integration interface and protocol models