The one command has a fixed lifecycle, supporting project commands, and
explicit expert projections of owner stages. Domain operations remain
owner-qualified identities; they do not become permanent top-level
subcommands.
Core lifecycle
| Command | Purpose |
|---|---|
one check | Validate the selected project, workspace, provider, adapter, or semantic package without application execution |
one test | Run root-owned application tests, conformance actions, simulation, or exact replay |
one invoke | Invoke one exact operation reachable from the selected root |
one plan | Produce an immutable project, release, admission, or publication plan without mutation |
one build | Materialize exact per-root artifacts from locked inputs and an authorized action graph |
one apply | Begin or resume one exact reviewed plan as a journaled operation |
one inspect | Resolve one owner-qualified subject through its selected owner adapter |
The ordinary path is:
one setup
one sync
one check
one test
one invoke <operation-id> request.json
one plan production
one build --root <root-id>
one observe production
one release production build:sha256:<build-digest>
one approve plan:<PlanId>
one apply plan:<PlanId>
one inspect operation:<OperationId>When scope has exactly one valid root, the interface may infer it. Choices that change meaning, artifacts, authority, placement, cost, target, or assurance remain explicit.
Project and authoring tools
| Command | Purpose |
|---|---|
one init | Create or adopt an application, provider, or adapter project through the canonical one.one lifecycle |
one source | Acquire, compare, and safely refresh one exact provider-resolved source snapshot |
one package | Add, remove, update, and inspect explicit root-scoped package selections and lock entries |
one sync | Derive and review the exact atomic lock change required by current source |
one update | Propose newer exact selections against an exact registry or catalog observation |
one bundle | Create or import an offline dependency, tool, and trust bundle |
one publish | Plan or execute a separately authorized package or distribution publication |
one setup | Materialize reversible standard local packages, provider inputs, and protected-store bindings |
one fmt | Format the .one envelope and known language regions while preserving unknown bodies byte-for-byte |
one lsp | Serve source, package, semantic, and source-transaction editor support |
one docs | Materialize documentation from exact normalized public contracts |
one export | Produce a read-only receipted interoperability, source, client, or distribution projection |
one clean | Remove reconstructible local state only |
one gc | Collect unreachable CAS and cache objects under owner retention rules |
one reset local | Reset durable local state only with explicit dispositions for data, unresolved effects, and protected evidence |
Package and editor operations update canonical source and one.lock through
revision-checked transactions. They do not create a second manifest, activate
code by installation, or turn a dependency into a provider selection.
sync and update produce reviewable lock proposals. Check, Build, tests,
editors, and language servers never mutate the accepted lock implicitly.
clean cannot remove durable material, and gc follows reachability from the
lock, artifacts, plans, journals, retained evidence, snapshots, and sessions.
Expert owner stages
These commands expose existing owner operations for experts and automation; they are not extra lifecycle stages and cannot bypass a missing predecessor.
| Command | Owner operation |
|---|---|
one acquire | Acquire an exact source or package without accepting its meaning |
one analyze | Run exact implementation-language analysis and effect summaries |
one infer | Produce exact or conservative inference and requirement consequences |
one project | Materialize a deterministic projection with its receipt |
one admit | Evaluate governed admission for an exact claim, artifact, and scope |
one select | Select providers and topology deterministically without mutation |
one observe | Read owner-qualified observations |
one approve | Record an external approval decision without issuing an implicit grant |
one reconcile | Resume or inspect recovery of one exact unresolved operation |
one status | Present the current owner-qualified operational disposition |
Interactive and automation interfaces
| Command | Purpose |
|---|---|
one dev | Run the framework and API development session selected by one exact application root |
one verify | Orchestrate checks, tests, configured Build verification, and policy proof without product mutation |
one release <environment> <build-ref> | Produce release-intent and apply plans, stopping before apply |
one tui | Open the persistent native workspace for overview, setup, authentication, agents, and inspection |
one shell | Enter an interactive session over fixed One commands, typed inspection projections, and an explicit human host-program lane |
one daemon serve / one daemon status | Illustrative end-product interface for an explicitly selected optional local coordination service |
one agent | Configure, run, and resume one bounded headless agent task |
one mcp | Serve the typed automation operations over an admitted MCP transport |
one lint | Run exact selected source tools and return diagnostics or edit proposals |
one debug | Open an exact capability-scoped debug session |
one decommission | Construct a governed removal and data-disposition plan |
These are projections over public owner operations, not alternate lifecycles. TUI, shell, agent, MCP, CI, and SDK callers cannot bypass source scope, exact locks, root closure, planning, Build authority, approvals, or reconciliation.
The shell's human host-program lane is deliberately separate. Direct argv, byte pipelines, redirection, conditions, bounded jobs, and session-local environment changes remain ordinary host activity. They produce no One semantic, Build, deployment, authority, or History claim and are unavailable to agents and automation as a hidden execution escape.
one release never applies by environment name. It emits exact plan and
evidence references. one approve records the approval; apply obtains the
applicable fresh grant and begins or resumes the journaled operation.
Authentication setup may materialize protected machine-local bindings, while
source and plans retain only typed requirements and references.
Exact operations, friendly projections
An operation contract defines inputs, outputs, domain faults, effects, approvals, planning, and reconciliation. The CLI, Rust and peer-language SDKs, HTTP endpoints, UI actions, MCP tools, and agents can project the same contract.
Friendly aliases are accepted only when the exact lock resolves them to one identity. Plans, approvals, receipts, automation, and inspection retain exact owner-qualified identities.
Output and diagnostics
--format human|json applies uniformly. Human output leads with the result and
smallest useful next action. Machine output uses stable versioned event streams
of owner envelopes and typed diagnostics; consumers never scrape human output.
Diagnostics identify the source span, owner, lifecycle stage, violated contract, minimal conflict, and responsible next action. Delegated compiler, provider, and platform failures remain source-mapped without forcing users to learn their command syntax.
Canonical owner: Developer Interface.
See dependencies and toolchains, One Shell, and the local daemon.