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 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 access is currently binary - either all outbound connections are allowed, or all are blocked. There is no per-host or per-domain filtering.Granular network filtering (e.g., allowing only specific domains like api.anthropic.com) is a desired feature but not yet supported. Apple Seatbelt has technical limitations that make per-host filtering challenging and would require significant experimentation to implement correctly. This feature may be added in a future release.

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

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

Secrets Options

`--secrets`

Load secrets from the system keystore (macOS Keychain / Linux Secret Service) and inject them as environment variables.

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

# Use with profile (loads secrets defined in profile's [secrets] section)
nono run --profile claude-code --secrets -- claude

Secrets 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()

See Secrets Management for full documentation on storing and using secrets.

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

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

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

​nono shell Options

​--shell

​Command Blocking

​--allow-command

​--block-command

​Secrets Options

​--secrets

​Profile Options

​--profile, -p

​--workdir

​--allow-cwd

​Operational Flags

​--dry-run

​--verbose, -v

​--config, -c

​nono why Options

​--path

​--op

​--host

​--port

​--json

​--self

​Capability Context Options

​nono setup Options

​--check-only

​--profiles

​--shell-integration

​--verbose, -v

​Exit Codes

​Path Resolution

​Combining Flags

​Examples

Global Options

`--silent`, `-s`

Commands

`nono run`

`nono shell`

`nono why`

`nono learn`

`nono setup`

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

`nono shell` Options

`--shell`

Command Blocking

`--allow-command`

`--block-command`

Secrets Options

`--secrets`

Profile Options

`--profile`, `-p`

`--workdir`

`--allow-cwd`

Operational Flags

`--dry-run`

`--verbose`, `-v`

`--config`, `-c`

`nono why` Options

`--path`

`--op`

`--host`

`--port`

`--json`

`--self`

Capability Context Options

`nono setup` Options

`--check-only`

`--profiles`

`--shell-integration`

`--verbose`, `-v`

Exit Codes

Path Resolution

Combining Flags

Examples