Metadata-Version: 2.4
Name: charter-cli
Version: 0.0.1
Summary: The `charter` command: durable workflow-as-code from the terminal.
Project-URL: Homepage, https://github.com/charter-tool/charter
Project-URL: Repository, https://github.com/charter-tool/charter
Project-URL: Issues, https://github.com/charter-tool/charter/issues
Project-URL: Changelog, https://github.com/charter-tool/charter/blob/main/CHANGELOG.md
Author: Paulo Alvarado Garcia
License: MIT
Keywords: agent,automation,cli,workflow,yaml
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: charter-core<0.1,>=0.0.1
Requires-Dist: charter-integration-sdk<0.1,>=0.0.1
Requires-Dist: click>=8.0
Description-Content-Type: text/markdown

# 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.

```bash
pip install charter-cli
charter --help
```

For the workflow model, config files, and shared examples, see the main [Charter README](../../README.md).

## 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

```text
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:

```bash
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:

```bash
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:

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

Discover workflows for agents or tooling:

```bash
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:

```bash
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:

```bash
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`](../charter-core/README.md): internal runtime engine used by the CLI
- [`charter-integration-sdk`](../charter-integration-sdk/README.md): integration interface and protocol models
