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 --output one.lock.proposed
one check
one test
one invoke <operation-id> request.json
one plan
one build --root <root-id>
one observe <subject-ref>
one release production build:sha256:<build-digest>
one approve plan:<digest>
one apply plan:<digest>
one inspect operation:<digest>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.
Scope and addressability
Three flags select what a command operates on. The CLI never guesses past an ambiguity; an inferred scope is printed in human output.
| Flag | Selects | Ambiguity behavior |
|---|---|---|
--workspace <dir> | The containing project or workspace | Rejected outside every declared project |
--project <id> | One project inside a workspace | Required when more than one project matches |
--root <id> | One root inside a project; may be PROJECT/ROOT | Required when more than one root matches |
Reference roles
A reference is <role>:<owner-qualified-identity> for a human, where the
identity is namespace#Name@lane for a named record or sha256:<hex> for a
content-addressed value. A plan or operation reference is <role>:<digest> for
the human CLI, where the
digest is sha256:<hex>; the owner-qualified exact reference is
one.deployment.local.release#Plan@1:sha256:<hex>. Prose uses plan:<digest>
and operation:<digest>; copyable examples use plan:sha256:<hex> and
operation:sha256:<hex>. A short alias is admissible only when the selected
lock resolves it unambiguously. Machine output always emits the exact
owner-qualified reference. plan:, operation:, and other roles never stack a
role prefix over a generic identity prefix or a bare revision:/stable:
token.
The lifecycle uses one closed role vocabulary for human references. Each command
documents which roles it resolves; one inspect and one reconcile resolve the
exact subjects described in
inspect and operate.
| Role | Resolves to |
|---|---|
plan | An immutable reviewed plan |
operation | A journaled apply or reconcile operation |
release | A deployment release record |
artifact | A Build artifact |
build | A Build report |
effect | An external effect relationship |
observation | An owner-qualified observation |
grant | An authority grant |
approval | An external approval decision |
snapshot | A retained source or state snapshot |
invocation | A recorded operation invocation |
Machine output always emits the exact owner-qualified reference; a role prefix is a human convenience and is never the identity.
Project and authoring tools
| Command | Purpose |
|---|---|
one init | Create or adopt an application 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 | Write an exact lock proposal with --output, or accept a complete explicitly reviewed source-and-lock transaction |
one update | Propose newer exact selections against an exact registry or catalog observation |
one bundle | install validates and materializes a verified archive; assemble builds a base-free distribution from exact published packages and Build evidence; archive packages a distribution with its executable |
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 --output and update produce reviewable lock proposals. Accepting a
whole-graph proposal uses sync with all three exact --proposed-source,
--proposed-lock, and --dependency-comparison inputs. 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 auth admit | Evaluate governed or accountable admission for an exact claim |
one auth status | Show the selected local owner and current Authority configuration |
one auth oidc | Materialize one exact local OIDC JWT trust configuration |
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 |
one releases | Enumerate releases reachable from the selected project or workspace |
one observe takes an exact owner-qualified subject reference (for example a
release or observation subject), not an environment or stage name. one plan
takes no positional subject; scope, profile, and target are explicit flags.
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 syntax; not a current command. 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 service host | Host one exact completely applied local release |
one decommission <subcommand> | 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.