# CLI model

One keeps a small universal command vocabulary. Domain-specific behavior is
projected from exact operation contracts rather than hard-coded into command
parsing.

> **End-product contract:** Individual commands are available only where their
> owning implementation and tests provide evidence.

## Universal control commands

| Command | Purpose |
| --- | --- |
| `one check` | Validate the envelope, semantics, claimed implementations, policy, and compatibility without application execution |
| `one test` | Run unit, integration, simulation, conformance, fuzz, benchmark, or replay verification |
| `one invoke` | Invoke an exact operation that permits direct execution |
| `one plan` | Produce an immutable plan for one exact semantic operation |
| `one build` | Materialize exact per-root artifacts from the locked physical plan |
| `one apply` | Begin or resume one reviewed plan |
| `one inspect` | Resolve and inspect an exact subject, optionally following explanation edges |

## Universal tooling commands

| Command | Purpose |
| --- | --- |
| `one init` | Create or adopt a project, semantic domain, provider, or adapter |
| `one fmt` | Format the `.one` envelope and semantic sections and route executable bodies to exact language formatters |
| `one lsp` | Serve section-aware language and semantic-package tooling |
| `one auth` | Manage principals, credentials, approvals, grants, and break-glass evidence |
| `one export` | Produce a read-only receipted projection or distribution package |
| `one docs` | Materialize documentation from exact normalized contracts |

## Exact operation identities

High-level domain commands are operations:

```console
one plan acme.robotics#CommissionCell --cell welding-7
one plan one.deployment#Deploy --environment production
one inspect plan:<digest> --explain
one apply plan:<digest>
```

CLI, Rust, TypeScript, HTTP, UI, and automation surfaces project the same
operation identity and typed inputs, outputs, faults, effects, approval
requirements, and evidence.

A friendly alias such as `deploy` is generated only when the selected lock
resolves it unambiguously. Plans and receipts always retain the qualified
identity.

## Read-only checking

`one check` never writes `one.lock`. If a dependency is missing, it reports the
exact requirement and may emit a reviewable lock proposal. `one init` creates
or adopts the initial lock; subsequent dependency changes follow an explicit
reviewed operation.

## Inspection is owner-neutral

`one inspect` resolves a lock-qualified stable locator or an exact
content-addressed reference. The owner supplies the bounded inspection
contract and available views.

The CLI does not maintain a registry of semantic kinds, custom domains, IR
records, artifact families, or provider-specific subjects.

## Unsupported remains typed

If a requested semantic package, language tool, provider, planner
contribution, compiler, deployment realization, or evidence path is absent,
the command returns the owning typed unsupported, unsatisfied, or
missing-evidence result.

Canonical owner:
[Developer Interface](https://github.com/muijf/one/blob/main/systems/developer-interface/AGENTS.md).