# 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

```console
$ 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:

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

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

```console
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.

## Review consequence before effect

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

one> apply plan:<PlanId>
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:

```console
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/reference/cli),
[One TUI](/one/guides/one-tui),
[authority and trust](/one/platform/authority), and
[agents and automation](/one/guides/agents-and-automation).