> ## Documentation Index
> Fetch the complete documentation index at: https://nativeharness.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# nhar

> The command line. Create a workspace, run a command in its sandbox, chat with a model that works in it, export it — every layer, from a terminal.

```bash theme={null}
npm install -g @nativeharness/cli
```

Installs `nhar`, and `nativeharness` in full. Without installing: `npx -p @nativeharness/cli nhar`.

<Note>
  **`nhar` and `nh` are different programs.** `nhar` is this CLI, on your machine, and it can do
  everything — including delete a workspace. `nh` is the
  [connector shim](/concepts/how-it-works): a small command that exists only *inside* a
  sandbox, for the model to reach connectors with, and it can do nothing else. You will never
  type `nh` yourself, and nothing you install puts it on your PATH.
</Note>

## Workspaces

```bash theme={null}
nhar create [name]        # a workspace, with you granted commit on /
nhar ls                   # every workspace in the root
nhar inspect <id>         # sandbox spec, permissions, files, recent sessions
nhar rm <id>              # delete it and its history
```

`create` grants the acting user permission. Without that the workspace would exist and refuse
every command, because `BashTool` checks that the session's actor is in `permissions`.

## Work

```bash theme={null}
nhar exec <id> "npm test"          # in the workspace's sandbox, streamed; exits with its status
nhar files <id>                    # what the workspace owns
nhar cat <id> /dist/report.txt
nhar put <id> /src/main.js --from ./main.js     # or from stdin
```

`exec` hydrates the workspace's files into a sandbox, runs the command, prints its output as it
arrives, syncs the changes back, and prints how many files changed. `--timeout <seconds>` caps
it.

## Agent

```bash theme={null}
nhar chat <id>                              # interactive
nhar chat <id> -m "add a test for the parser"   # one turn, then exit
  --model <spec>       anthropic · anthropic/claude-opus-5 · openai/gpt-5 · ollama/<name> · scripted:<file>
  --session <id>       continue an earlier session
  --yes                allow held commands without asking (for CI)
```

Tokens stream as the model writes; commands print as they run, with output live; a held
command asks `allow it? [y/N]`; a question from the model is asked inline with numbered
options. Ctrl+C cancels the **turn** — durably, recorded with who stopped it — and a second
Ctrl+C leaves.

With no model configured it exits 2 and lists the environment variables to set.

## Portability

```bash theme={null}
nhar export <id> [dest]    # a directory with a checksum; dest defaults to the cwd
nhar import <src>          # into this root, with reconciliation reported
```

## Host

```bash theme={null}
nhar doctor                # root, actor, and whether the sandbox engine answers; non-zero if not
```

For the engine itself, `npx nativesandbox doctor --deep` goes further and proves the kernel is
holding a memory limit.

## Options and environment

| Flag                   | Env               |                                                               |
| ---------------------- | ----------------- | ------------------------------------------------------------- |
| `--root <dir>`         | `NH_ROOT`         | where workspaces live — default `~/.nativeharness/workspaces` |
| `--sandbox-root <dir>` | `NH_SANDBOX_ROOT` | where sandbox directories live                                |
| `--socket <path>`      |                   | the engine socket, overriding auto-detection                  |
| `--actor <name>`       | `NH_ACTOR`        | who is acting — default: your username                        |
| `--model <spec>`       | `NH_MODEL`        | see above                                                     |
| `--json`               |                   | machine-readable output where it makes sense                  |

## Exit codes

|                   |                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------- |
| `0`               | it worked; for `chat`, the turn completed                                          |
| the command's own | `exec` passes it through                                                           |
| `1`               | it failed — no engine, no such workspace                                           |
| `2`               | you typed it wrong, or no model is configured                                      |
| `3` / `4`         | `chat`: the turn ended `needs_continuation` with no terminal to answer / `blocked` |
| `130`             | `chat`: cancelled                                                                  |