One Shell#

One Shell is the interactive, line-oriented interface for ordinary host work and typed One operations. It is not a new project model, an automatic trust boundary, or a shell language hidden inside .one source.

Start explicitly#

$ one shell --workspace .
One Shell · parcelhub/ledger · ready
one>

Outside a One project, the same command starts in host-only context and does not invent one.one or one.lock. Project operations still use deterministic discovery from the selected directory.

Use both command lanes#

Host programs keep ordinary byte and terminal behavior:

one> git status --short
one> cargo test -p parcelhub
one> git log --oneline | head -20

One lifecycle commands call the same versioned handlers as the CLI, TUI, editors, MCP, and agents:

one> check
one> test --root ledger
one> build --root ledger
one> inspect deployments | where state == degraded | select app env state

Typed pipelines retain exact owner schemas. External pipelines carry bytes. Crossing between them is always explicit:

one> inspect releases | encode json | command jq '.items[].artifact'
one> kubectl get pods -o json | decode json as acme.k8s#PodList@1 | validate

The shell never guesses a schema from bytes or parses human CLI output to recover a typed value.

Save and run a bounded program#

A repeated sequence of fixed One commands can be saved as an ordinary .onesh program and run noninteractively. The extension distinguishes a saved shell program from semantic .one source:

one shell --workspace . --file verify.onesh
one shell --workspace . --command 'check'            # one inline command source
one shell --workspace . --file verify.onesh --check  # validate without running

A saved program uses only the fixed One command vocabulary and the typed lane. It is not a general shell language and cannot bypass scope, lifecycle, or authority. Shell modules resolve from an explicit --module-root in deterministic order, and each must be one regular .onesh file. --preferences <file> selects machine-local presentation preferences, which never carry project meaning, provider configuration, credentials, or executable startup code.

This bounded saved-program interface is part of the currently demonstrated shell surface; the interactive host and typed lanes above remain the primary experience.

Review consequence before effect#

one> release production
# prints the immutable plan and relevant cost, authority, and topology change

one> apply plan:<digest>
Approve production release? [y/N]

release stops before apply. Approval, grants, journaling, dispatch, and reconciliation remain distinct. Losing the terminal after possible dispatch does not make retry safe; resume with the operation identity or use reconcile.

Host programs run with the user's host authority. One operations use only the selected root, lock, binding, and grant. resolve <name> explains which lane and executable a command selects. Merely changing directory never loads project code, a shell module, credentials, or provider configuration.

Jobs, history, and configuration#

Foreground and background host pipelines use ordinary job control:

one> cargo test --workspace &
[1] running cargo test --workspace
one> jobs
one> fg 1

A shell job number is session-local; it is not a workflow, deployment, operation, attempt, or History identity. Recall history is local interaction convenience and does not become causal One History.

Machine-local preferences may choose color, bounded recall retention, prompt fields, keybindings, editor behavior, and explicitly imported host environment. They do not carry project meaning, provider configuration, credentials, or executable startup code. Project and domain capabilities come only from the current one.one, selected sources, and exact lock.

One Shell works inside ordinary terminal multiplexers. Opening a TUI or agent beside the shell is an explicit selected pane action; terminal placement does not merge authority, state, or session identity.

See the CLI reference, One TUI, authority and trust, and agents and automation.