CLI Reference - Nono Docs

Complete reference for all nono command-line flags.

Global Options

These options work with all commands.

`--silent`, `-s`

Suppress all nono output (banner, summary, status messages). Only the executed command’s output will be shown.

nono -s run --allow-cwd -- my-agent
nono --silent why --path ~/.ssh/id_rsa --op read

Commands

`nono run`

Run a command inside the sandbox.

nono run [OPTIONS] -- <COMMAND> [ARGS...]

`nono shell`

Start an interactive shell inside the sandbox.

nono shell [OPTIONS]

`nono why`

Check why a path or network operation would be allowed or denied. Designed for both human debugging and programmatic use by AI agents.

nono why --path <PATH> --op <OP> [OPTIONS]
nono why --host <HOST> [--port <PORT>] [OPTIONS]
nono why --self --path <PATH> --op <OP> [OPTIONS]  # Inside sandbox

`nono learn`

Trace a command to discover required filesystem paths. Uses strace to monitor file accesses and outputs paths that would need to be allowed in a nono profile. (Linux only)

nono learn [OPTIONS] -- <COMMAND> [ARGS...]

`nono setup`

Set up nono on this system. Verifies installation, tests sandbox support, and optionally generates example profiles.

nono setup [OPTIONS]

`nono trust`

Manage instruction file attestation. Sign, verify, and manage trust for AI agent instruction files.

nono trust <SUBCOMMAND>

Subcommands:

sign - Sign instruction files
sign-policy - Sign a trust policy file
verify - Verify instruction files against the trust policy
list - List instruction files and their verification status
keygen - Generate a new signing key pair
export-key - Export the public key for a signing key

`nono learn` Options

nono learn is only available on Linux as it requires strace. The command runs WITHOUT sandbox restrictions to discover what paths your application needs.

`--profile`, `-p`

Compare against an existing profile to show only missing paths.

nono learn --profile opencode -- opencode

`--toml`

Output discovered paths as a TOML fragment suitable for a profile.

nono learn --toml -- my-app > paths.toml

`--timeout`

Limit trace duration in seconds.

nono learn --timeout 30 -- my-long-running-app

`--all`

Show all accessed paths, not just those that would be blocked by the sandbox.

nono learn --all -- my-app

`--verbose`, `-v`

Enable verbose output. Can be specified multiple times.

nono learn -vv -- my-app

`nono run` Options

Directory Permissions

These flags grant recursive access to directories and all their contents.

`--allow`, `-a`

Grant read and write access to a directory.

nono run --allow ./project -- command
nono run -a ./src -a ./tests -- command

Can be specified multiple times to allow multiple directories.

`--read`, `-r`

Grant read-only access to a directory.

nono run --read ./config -- command
nono run -r /etc/myapp -- command

Useful for source code directories that shouldn’t be modified.

`--write`, `-w`

Grant write-only access to a directory.

nono run --write ./output -- command
nono run -w ./logs -- command

Useful for output directories where reading existing content isn’t needed.

File Permissions

These flags grant access to individual files only (non-recursive).

`--allow-file`

Grant read and write access to a single file.

nono run --allow-file ./database.sqlite -- command

`--read-file`

Grant read-only access to a single file.

nono run --read-file ./config.toml -- command
nono run --read-file ~/.gitconfig -- command

`--write-file`

Grant write-only access to a single file.

nono run --write-file ./output.log -- command

Network Control

`--net-block`

Block all network access. Network is allowed by default.

# Block network for a build process that should be offline
nono run --allow-cwd --net-block -- cargo build

`--network-profile`

Use a predefined network profile for host-level filtering. When set, outbound traffic is routed through a localhost proxy that only allows connections to hosts in the profile.

# Use the claude-code network profile
nono run --allow-cwd --network-profile claude-code -- claude

# Use minimal profile (LLM APIs only)
nono run --allow-cwd --network-profile minimal -- my-agent

Available profiles: claude-code, minimal, enterprise. See Network Proxy for details.

--network-profile and --proxy-allow activate proxy mode, which forces supervised execution. The proxy runs in the unsandboxed parent process.

`--proxy-allow`

Allow a specific host through the network proxy. Can be specified multiple times. Activates proxy mode if not already active.

# Allow specific hosts
nono run --allow-cwd --proxy-allow api.openai.com --proxy-allow api.anthropic.com -- my-agent

# Combine with a network profile for additional hosts
nono run --allow-cwd --network-profile minimal --proxy-allow custom-api.example.com -- my-agent

`--proxy-credential`

Enable credential injection for a named service via the reverse proxy. The service must be either a built-in service (openai, anthropic, gemini, google-ai) or defined as a custom credential in your profile. Credentials are loaded from the system keyring under the nono service name.

# Inject OpenAI credentials (loads from keyring account "openai_api_key")
nono run --allow-cwd --network-profile claude-code --proxy-credential openai -- my-agent

# Multiple credentials
nono run --allow-cwd --network-profile claude-code \
  --proxy-credential openai --proxy-credential anthropic -- my-agent

The proxy sets OPENAI_BASE_URL, ANTHROPIC_BASE_URL, etc. in the child environment so SDKs route through the proxy automatically. Custom credentials can be defined in profiles for APIs not covered by the built-in services:

{
  "network": {
    "custom_credentials": {
      "my-api": {
        "upstream": "https://api.example.com",
        "credential_key": "my_api_key"
      }
    }
  }
}

See Credential Injection for complete documentation including custom credential definitions.

`--external-proxy`

Chain outbound connections through an external (enterprise) proxy. The default deny list (cloud metadata, private networks) is still enforced.

nono run --allow-cwd --network-profile enterprise --external-proxy squid.corp:3128 -- my-agent

`--allow-bind`

Allow the sandboxed process to bind and listen on a TCP port. Required when running server applications (like AI gateways) in proxy mode.

# Allow OpenClaw gateway to listen on its default port
nono run --profile openclaw --allow-bind 18789 \
  --proxy-credential openai -- openclaw gateway

# Allow a development server
nono run --allow-cwd --network-profile developer --allow-bind 3000 -- npm run dev

macOS limitation: Seatbelt cannot filter by port number. When --allow-bind is specified on macOS, the sandbox permits binding to any port and accepting inbound connections from any source.This is a broader permission than intended, but the security impact is limited:

Outbound connections are still restricted to allowed hosts via the proxy
Filesystem access is still limited to granted paths
An attacker would need to know the machine’s IP and which port the agent opened
Even if they connect, they can only send data in — the agent cannot exfiltrate responses to arbitrary hosts

On Linux with Landlock ABI v4+, per-port filtering is enforced and only the specified ports can be bound.

--allow-bind only has effect in proxy mode (when --network-profile or --proxy-allow is active). Without proxy mode, network operations use the default OS-level allow/deny and bind is not restricted.

`nono shell` Options

nono shell supports the same permission, profile, secrets, and dry-run flags as nono run, plus:

`--shell`

Override the shell binary.

nono shell --allow-cwd --shell /bin/zsh

Command Blocking

`--allow-command`

Allow a normally-blocked dangerous command. By default, destructive commands like rm, dd, chmod are blocked. Use this flag to override for a specific command.

# Allow rm (blocked by default)
nono run --allow-cwd --allow-command rm -- rm ./temp-file.txt

# Allow multiple commands
nono run --allow-cwd --allow-command rm --allow-command mv -- my-script.sh

Even with --allow-command, the kernel sandbox still restricts file operations to granted paths. A command can only affect files within directories you explicitly allowed.

Command blocking is a best-effort surface-level control. It matches against the executable name being invoked directly. It does not prevent a process from performing the equivalent operation through language-level APIs (e.g., os.remove() in Python), shell built-ins, or renamed binaries. For hard protection against destructive filesystem operations, rely on kernel-enforced deny groups (deny.access, deny.unlink) and path-based sandboxing, which apply regardless of how the operation is invoked.

`--block-command`

Block an additional command beyond the default blocklist.

# Block a custom tool in addition to defaults
nono run --allow-cwd --block-command my-dangerous-tool -- my-script.sh

Credential Options

`--env-credential`

Load credentials from the system keystore (macOS Keychain / Linux Secret Service) and inject them as environment variables. The sandboxed process can read these credentials directly.

# Load specific credentials by account name
nono run --allow-cwd --env-credential openai_api_key,anthropic_api_key -- my-agent

# Use with profile (loads credentials defined in profile's [env_credentials] section)
nono run --profile claude-code --env-credential -- claude

Credentials are:

Loaded before the sandbox is applied (keystore access blocked after)
Auto-named by uppercasing: openai_api_key becomes $OPENAI_API_KEY
Zeroized from memory after exec()

For network API keys, prefer --proxy-credential instead for credential isolation — the agent never sees the real API key. See Secrets Management for full documentation on storing and using credentials.

Profile Options

`--profile`, `-p`

Use a named profile (built-in or from ~/.config/nono/profiles/).

nono run --profile claude-code -- claude
nono run -p openclaw -- openclaw gateway

`--workdir`

Working directory for $WORKDIR expansion in profiles (defaults to current directory).

nono run --profile claude-code --workdir ./my-project -- claude

`--allow-cwd`

Allow access to the current working directory without prompting. By default, nono prompts interactively for CWD sharing. The access level is determined by the profile’s [workdir] config or defaults to read-only.

# Non-interactive mode (e.g., CI/CD)
nono run --profile claude-code --allow-cwd -- claude

# Silent mode requires --allow-cwd (cannot prompt)
nono -s run --profile claude-code --allow-cwd -- claude

Execution Mode Flags

`--rollback`

Enable atomic rollback snapshots for the session. Takes content-addressable snapshots of writable directories so you can restore to the pre-session state after the command exits. Automatically selects supervised execution.

nono run --rollback --profile claude-code -- claude
nono run --rollback --allow-cwd -- my-agent

`--supervised`

Enable the approval sidecar for runtime capability expansion. On Linux, the supervisor can grant additional filesystem access via seccomp user notification when the sandboxed process requests it.

nono run --supervised --allow-cwd -- my-agent

Can be combined with --rollback for both snapshots and capability expansion:

nono run --rollback --supervised --allow-cwd -- my-agent

`--no-rollback-prompt`

Suppress the interactive post-exit review when using --rollback. Snapshots are still taken but the user is not prompted to review or restore changes. Useful for scripting.

nono run --rollback --no-rollback-prompt --allow-cwd -- my-agent

`--exec`

Use direct execution mode. nono applies the sandbox and then exec()s directly into the target command. No parent process remains.

nono run --exec --allow-cwd -- my-command

`--no-diagnostics`

Suppress the diagnostic footer when the command exits non-zero. Useful for scripts that parse stderr and need stable output.

nono run --no-diagnostics --allow-cwd -- my-command

Operational Flags

`--dry-run`

Show what capabilities would be granted without actually executing the command or applying the sandbox.

nono run --allow-cwd --read /etc --dry-run -- my-agent

Output:

Capabilities that would be granted:
  [rw] /Users/luke/project
  [r-] /etc
  [net] allowed

Would execute: my-agent

`--verbose`, `-v`

Increase logging verbosity. Can be specified multiple times.

Flag	Level	Output
(none)	Error	Only errors
`-v`	Info	Informational messages
`-vv`	Debug	Detailed debug output
`-vvv`	Trace	Full trace output

nono run -vvv --allow-cwd -- command

`--trust-override`

Disable trust verification for instruction files. Skips the pre-exec trust scan that verifies cryptographic signatures on instruction files (SKILLS*, CLAUDE*, AGENT*, .claude/**/*.md). For development and testing only.

nono run --trust-override --allow-cwd -- my-agent

Using --trust-override in production is not recommended. It disables the entire instruction file attestation pipeline, allowing unsigned or tampered instruction files to be read by the sandboxed process.

`--config`, `-c`

Specify a configuration file path.

nono run --config ./nono.toml -- command

Configuration file support is planned for a future release.

`nono why` Options

The why command checks why a path or network operation would be allowed or denied. It’s designed for both human debugging and programmatic use by AI agents.

`--path`

The filesystem path to check.

nono why --path ~/.ssh/id_rsa --op read
nono why --path ./my-project --op write

`--op`

The operation to check: read, write, or readwrite. Defaults to read if not specified.

nono why --path ./src --op read
nono why --path ./output --op write
nono why --path ./data --op readwrite

`--host`

Network host to check (instead of --path).

nono why --host api.openai.com --port 443

`--port`

Network port (default: 443). Used with --host.

nono why --host example.com --port 8080

`--json`

Output JSON instead of human-readable format. Useful for programmatic use by AI agents.

nono why --json --path ~/.ssh --op read
# {"status":"denied","reason":"sensitive_path","category":"SSH keys and config",...}

`--self`

Query current sandbox state from inside a sandboxed process. This allows agents to introspect their own capabilities.

# Inside a sandbox:
nono why --self --path /tmp --op write --json

Capability Context Options

When checking paths outside a sandbox, you can simulate a capability context:

# Check if ./src would be writable with --allow .
nono why --path ./src --op write --allow .

# Check against a profile
nono why --path ~/.config --op read --profile claude-code

Available context flags:

--allow, -a - Directories with read+write access
--read, -r - Directories with read-only access
--write, -w - Directories with write-only access
--allow-file - Single files with read+write access
--read-file - Single files with read-only access
--write-file - Single files with write-only access
--net-block - Block network access
--profile, -p - Use a named profile
--workdir - Working directory for $WORKDIR expansion

`nono trust` Options

`nono trust sign`

Sign instruction files, producing bundles for verification.

nono trust sign <FILES...>                 # Sign specific files
nono trust sign --all                      # Sign all instruction files in CWD
nono trust sign SKILLS.md --key my-key     # Use a specific key

Option	Description
`--all`	Sign all instruction files matching trust policy patterns
`--key <KEY_ID>`	Key ID from system keystore (default: “default”)
`--keyless`	Use Sigstore keyless signing (CI environments only)
`--policy <FILE>`	Trust policy file (default: auto-discover)

When signing multiple files, a single .nono-trust.bundle multi-subject bundle is created. Single-file signing creates per-file .bundle sidecars.

`nono trust sign-policy`

Sign a trust policy file.

nono trust sign-policy                     # Sign trust-policy.json in CWD
nono trust sign-policy path/to/policy.json # Sign specific file
nono trust sign-policy --key my-key        # Use a specific key

`nono trust verify`

Verify instruction files against the trust policy.

nono trust verify <FILES...>               # Verify specific files
nono trust verify --all                    # Verify all instruction files in CWD
nono trust verify --policy path/to/policy  # Use specific trust policy

`nono trust list`

List instruction files and their verification status.

nono trust list                            # Human-readable output
nono trust list --json                     # JSON output

`nono trust keygen`

Generate an ECDSA P-256 signing key pair and store it in the system keystore.

nono trust keygen                          # Default key ID ("default")
nono trust keygen --id my-signing-key      # Named key

`nono trust export-key`

Export the public key for use in trust policy public_key fields.

nono trust export-key                      # Export default key (base64 DER)
nono trust export-key --id my-key          # Export named key
nono trust export-key --pem                # Output as PEM format

`nono setup` Options

`--check-only`

Only verify installation and sandbox support, don’t create any files.

nono setup --check-only

`--profiles`

Generate example user profiles in ~/.config/nono/profiles/.

nono setup --profiles

`--shell-integration`

Show shell integration instructions (aliases, etc.).

nono setup --shell-integration

`--verbose`, `-v`

Show detailed information during setup. Can be specified multiple times.

nono setup -v --profiles

Exit Codes

Code	Meaning
0	Command executed successfully
1	nono error (invalid arguments, sandbox failure)
*	Exit code from the executed command

Path Resolution

All paths are canonicalized before the sandbox is applied:

Relative paths are resolved to absolute paths
Symlinks are followed and resolved
Parent directory references (..) are resolved

This prevents symlink escape attacks where a malicious agent creates a symlink pointing outside the allowed directory.

# These are equivalent if ./project resolves to /home/user/project
nono run --allow ./project -- command
nono run --allow /home/user/project -- command

Combining Flags

Flags can be combined freely:

nono run \
  --allow ./project \
  --read ~/.config/myapp \
  --write ./logs \
  --read-file ~/.gitconfig \
  -vv \
  -- my-agent --arg1 --arg2

Examples

See the Examples page for common usage patterns.

Getting Started

Features

Agents & Clients

Platform Internals

Reference

Development

​Global Options

​--silent, -s

​Commands

​nono run

​nono shell

​nono why

​nono learn

​nono setup

​nono trust

​nono learn Options

​--profile, -p

​--toml

​--timeout

​--all

​--verbose, -v

​nono run Options

​Directory Permissions

​--allow, -a

​--read, -r

​--write, -w

​File Permissions

​--allow-file

​--read-file

​--write-file

​Network Control

​--net-block

​--network-profile

​--proxy-allow

​--proxy-credential

​--external-proxy

​--allow-bind

​nono shell Options

​--shell

​Command Blocking

​--allow-command

​--block-command

​Credential Options

​--env-credential

​Profile Options

​--profile, -p

​--workdir

​--allow-cwd

​Execution Mode Flags

​--rollback

​--supervised

​--no-rollback-prompt

​--exec

​--no-diagnostics

​Operational Flags

​--dry-run

​--verbose, -v

​--trust-override

​--config, -c

​nono why Options

​--path

​--op

​--host

​--port

​--json

​--self

​Capability Context Options

​nono trust Options

​nono trust sign

​nono trust sign-policy

​nono trust verify

​nono trust list

​nono trust keygen

​nono trust export-key

​nono setup Options

​--check-only

​--profiles

​--shell-integration

​--verbose, -v

​Exit Codes

Global Options

`--silent`, `-s`

Commands

`nono run`

`nono shell`

`nono why`

`nono learn`

`nono setup`

`nono trust`

`nono learn` Options

`--profile`, `-p`

`--toml`

`--timeout`

`--all`

`--verbose`, `-v`

`nono run` Options

Directory Permissions

`--allow`, `-a`

`--read`, `-r`

`--write`, `-w`

File Permissions

`--allow-file`

`--read-file`

`--write-file`

Network Control

`--net-block`

`--network-profile`

`--proxy-allow`

`--proxy-credential`

`--external-proxy`

`--allow-bind`

`nono shell` Options

`--shell`

Command Blocking

`--allow-command`

`--block-command`

Credential Options

`--env-credential`

Profile Options

`--profile`, `-p`

`--workdir`

`--allow-cwd`

Execution Mode Flags

`--rollback`

`--supervised`

`--no-rollback-prompt`

`--exec`

`--no-diagnostics`

Operational Flags

`--dry-run`

`--verbose`, `-v`

`--trust-override`

`--config`, `-c`

`nono why` Options

`--path`

`--op`

`--host`

`--port`

`--json`

`--self`

Capability Context Options

`nono trust` Options

`nono trust sign`

`nono trust sign-policy`

`nono trust verify`

`nono trust list`

`nono trust keygen`

`nono trust export-key`

`nono setup` Options

`--check-only`

`--profiles`

`--shell-integration`

`--verbose`, `-v`

Exit Codes

Path Resolution

Combining Flags

Examples