CLI Reference

Synopsis

greywall [flags] [--] <command> [args...]
greywall -c "<shell string>"
greywall <subcommand> [args...]

Global Flags

Flag	Short	Description
--settings <path>	-s	Path to a JSON/JSONC config file. Defaults to ~/.config/greywall/greywall.json (macOS: ~/Library/Application Support/greywall/greywall.json)
--template <name>	-t	Apply a built-in or learned template by name (e.g., -t code)
--profile <names>		Comma-separated list of profiles to apply (e.g., --profile claude,python)
--proxy <url>		Override the SOCKS5 proxy URL (e.g., --proxy socks5://localhost:1080)
--port <port>	-p	Expose a port for inbound connections into the sandbox (repeatable)
--command <cmd>	-c	Run a shell command string (supports &&, ;, pipes)
--debug	-d	Verbose output: proxy activity, filter decisions, sandbox command
--monitor	-m	Show only violations and blocked requests (audit mode)
--learning		Trace filesystem access with strace/eslogger and auto-generate a config template
--version		Print the greywall version and exit
--help	-h	Show help

-m and -d together

You can combine both flags to get violation monitoring and the full sandbox command:

greywall -m -d -- npm install

-p / --port

Expose ports for sandboxed servers so external processes can connect:

# Single port
greywall -p 3000 -c "npm run dev"

# Multiple ports
greywall -p 3000 -p 8080 -c "make start"

Subcommands

greywall check

Check that greywall and its dependencies are correctly installed.

greywall check

Verifies:

• Required binaries (bwrap, socat on Linux)
• Linux kernel security features (Landlock, seccomp, eBPF)
• Greyproxy installation and service status

greywall setup

Download and install Greyproxy, then start it as a service.

greywall setup

Installs greyproxy to ~/.local/bin/greyproxy and registers it as a systemd user service (Linux) or launchd agent (macOS).

greywall --linux-features

Print the Linux kernel security features available on the current system.

greywall --linux-features

Example output:

Linux Sandbox Features:
  Kernel: 6.8
  Bubblewrap (bwrap): true
  Socat: true
  Seccomp: true (log level: 2)
  Landlock: true (ABI v4)
  eBPF: true (CAP_BPF: true, root: false)

Feature Status:
  ✓ Minimum requirements met (bwrap + socat)
  ✓ Landlock available for enhanced filesystem control
  ✓ Violation monitoring available
  ✓ eBPF monitoring available (enhanced visibility)

greywall --list-templates

List all available built-in templates.

greywall --list-templates

greywall templates list

List all learned templates (generated by --learning mode).

greywall templates list

greywall templates show <name>

Print the content of a learned template.

greywall templates show opencode

greywall import --claude

Import permissions from a Claude Code settings file and convert them to a greywall config. See Importing from Claude Code for full documentation.

greywall import --claude
greywall import --claude --save
greywall import --claude -f ~/.claude/settings.json --save

greywall profiles list

List all available and saved profiles (built-in agent profiles and saved custom profiles).

greywall profiles list

Environment Variables

Variable	Description
GREYWALL_SANDBOX	Set to 1 inside sandboxed processes. Lets commands detect they are running under greywall.
GREYWALL_TEST_NETWORK	Set to 1 in smoke tests to enable network-dependent tests.
HTTP_PROXY / HTTPS_PROXY	Set by greywall to point to the local HTTP proxy (macOS and Linux fallback mode).
ALL_PROXY	Set by greywall to point to the SOCKS5 proxy.
GIT_SSH_COMMAND	Set by greywall on macOS to route SSH through the proxy.

Exit Codes

Code	Meaning
0	Success
1	Greywall error (config invalid, dependency missing, command blocked by policy)
Other	The exit code of the sandboxed command itself

Examples

# Sandbox a single command
greywall -- curl https://example.com

# Sandbox a shell pipeline
greywall -c "cat package.json | grep name"

# Use a built-in template
greywall -t code -- claude

# Use multiple profiles
greywall --profile claude,python -- claude

# Override proxy
greywall --proxy socks5://proxy.internal:1080 -- npm install

# Monitor what gets blocked without stopping the command
greywall -m -- pip install -r requirements.txt

# Learn filesystem access, then run normally
greywall --learning -- cargo build
greywall -- cargo build          # auto-loads learned template

# Expose dev server port
greywall -p 5173 -c "npm run dev"

# Debug with custom config
greywall -d -s ./greywall.json -- go test ./...

Config File Locations

Platform	Default path
Linux	~/.config/greywall/greywall.json
macOS	~/Library/Application Support/greywall/greywall.json
Legacy (both)	~/.greywall.json

Pass --settings <path> to use any other location. Config files support JSONC (JSON with comments).