Skip to main content

​
0x0 CLI Guide

This guide documents the CLI in this repository, from installation to advanced configuration.

​
Installation

Use one of the supported install methods: 
# Install script
curl -fsSL https://0x0.ai/install | bash

# Package managers
npm i -g @anonymous-dev/0x0@latest
pnpm add -g @anonymous-dev/0x0@latest
bun install -g @anonymous-dev/0x0@latest
brew install anonymous-dev-org/tap/0x0
brew install 0x0
scoop install 0x0
choco install 0x0
mise use -g 0x0
Verify: 
0x0 --version
0x0 --help

​
Core usage

  • Start TUI: 0x0 or 0x0 [project]
  • One-shot mode: 0x0 run "your prompt"
  • Headless server: 0x0 serve
  • Browser UI: 0x0 web
  • Attach to running server: 0x0 attach <url>
Global CLI options:
  • --help, -h
  • --version, -v
  • --print-logs
  • --log-level DEBUG|INFO|WARN|ERROR

​
Command reference

Top-level commands:
  • 0x0 / $0 [project]: start TUI (--model, --continue, --session, --fork, --prompt, --agent + network options)
  • 0x0 run [message..]: non-interactive prompt/command execution
  • 0x0 attach <url>: attach TUI to server (--dir, --session, --password)
  • 0x0 serve: start headless server (network options)
  • 0x0 web: start server and open browser (network options)
  • 0x0 acp: start ACP server (--cwd + network options)
  • 0x0 auth: credential management
  • 0x0 mcp: MCP server management
  • 0x0 agent: generate/list agents
  • 0x0 models [provider]: list models (--verbose, --refresh)
  • 0x0 session list: list sessions (--max-count, --format table|json)
  • 0x0 stats: usage/cost stats (--days, --tools, --models, --project)
  • 0x0 export [sessionID]: export session JSON
  • 0x0 import <file-or-share-url>: import session JSON/share URL
  • 0x0 pr <number>: checkout PR and launch 0x0
  • 0x0 github: GitHub agent install/run helpers
  • 0x0 upgrade [target]: upgrade CLI (--method)
  • 0x0 uninstall: remove installation/data (--keep-config, --keep-data, --dry-run, --force)
  • 0x0 debug: diagnostics (config, paths, lsp, ripgrep, file, skill, snapshot, agent, wait)
Network options shared by serve, web, TUI, and acp:
  • --port (default 0)
  • --hostname (default 127.0.0.1)
  • --mdns (default false)
  • --mdns-domain (default zeroxzero.local)
  • --cors <origin> (repeatable)

​
Configuration files

0x0 supports YAML, YML, JSON, and JSONC config files. Recognized filenames:
  • 0x0.yaml, 0x0.yml
  • zeroxzero.yaml, zeroxzero.yml
  • 0x0.json, 0x0.jsonc
  • zeroxzero.json, zeroxzero.jsonc

​
Global config

Primary location: Global.Path.config (XDG config path, app folder 0x0). Typical examples:
  • macOS/Linux: ~/.config/0x0/0x0.yaml
  • Windows: XDG config directory for the current user, under 0x0
Check exact runtime paths with: 
0x0 debug paths

​
Per-project config

Project config is discovered from the current directory upward to the repo/worktree root. For each directory in the chain, 0x0 checks:
  1. <dir>/<config-file>
  2. <dir>/.0x0/<config-file>
Example project config files:
  • ./0x0.yaml
  • ./.0x0/0x0.yaml
Important conflict rule:
  • If multiple project config files exist in the same directory level, 0x0 throws a conflict error.

​
.zeroxzero extension directories

In addition to YAML/JSON config files, 0x0 loads extension content from .zeroxzero directories:
  • .zeroxzero/agent/**/*.md or .zeroxzero/agents/**/*.md
  • .zeroxzero/command/**/*.md or .zeroxzero/commands/**/*.md
  • .zeroxzero/mode/*.md or .zeroxzero/modes/*.md
  • .zeroxzero/plugin/*.{ts,js} or .zeroxzero/plugins/*.{ts,js}
These are loaded from project scope and home scope.

​
Config precedence

Low to high precedence:
  1. Remote .well-known/zeroxzero config (when authenticated provider supports it)
  2. Global config (~/.config/0x0/...)
  3. ZEROXZERO_CONFIG file path override
  4. Project config files (0x0.yaml, .0x0/0x0.yaml, etc.)
  5. .zeroxzero directories (commands/agents/plugins/config)
  6. Inline ZEROXZERO_CONFIG_CONTENT JSON
  7. Managed enterprise config directory (highest):
    • macOS: /Library/Application Support/zeroxzero
    • Linux: /etc/zeroxzero
    • Windows: %ProgramData%\\zeroxzero

​
Global config YAML example

# yaml-language-server: $schema=https://zeroxzero.ai/config.json
$schema: https://zeroxzero.ai/config.json

theme: undertale
logLevel: INFO
model: zeroxzero/gpt-5.1
default_agent: build
share: manual
autoupdate: notify

server:
  hostname: 127.0.0.1
  port: 0
  mdns: false
  mdnsDomain: zeroxzero.local
  cors:
    - https://example.com

provider:
  openai:
    options:
      apiKey: "{env:OPENAI_API_KEY}"
      timeout: 300000

mcp:
  local-files:
    type: local
    command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."]
  remote-docs:
    type: remote
    url: https://example.com/mcp
    oauth:
      clientId: "{env:MCP_CLIENT_ID}"
      clientSecret: "{file:./secrets/mcp-client-secret.txt}"

compaction:
  auto: true
  prune: true

experimental:
  batch_tool: true
  mcp_timeout: 10000

​
Per-project config YAML example

Use project config for repo-specific behavior. ./0x0.yaml: 
# yaml-language-server: $schema=https://zeroxzero.ai/config.json
$schema: https://zeroxzero.ai/config.json

model: anthropic/claude-sonnet-4
default_agent: plan
knowledge:
  - This repo uses Bun workspaces
  - Use `bun test` for tests

permission:
  bash: ask
  edit: allow
  read: allow

watcher:
  ignore:
    - "**/dist/**"
    - "**/.next/**"
./.0x0/0x0.yaml can be used for a dedicated per-project settings file managed by the CLI.

​
Advanced configuration areas

  • agent: define primary/all agents, model overrides, prompts, permission rules, step limits
  • command: define reusable slash commands and templates
  • permission: global tool permission policy (ask, allow, deny) and path rules
  • provider: provider-specific API settings, model overrides, variant options, allow/deny lists
  • mcp: local and remote MCP servers, headers, OAuth, timeouts, enabled flags
  • lsp: language server mapping, commands, extensions, env, initialization
  • formatter: external formatter commands by language
  • prompt: override system prompt blocks and reminder strings
  • keybinds: customize TUI key mappings
  • tui: scroll speed, terminal notifications, diff rendering style, tint
  • skills: extra local/remote skill sources
  • experimental: feature toggles like batch tool and MCP timeout tuning

​
Config interpolation

Config text supports:
  • {env:VAR_NAME}: inject environment variable value
  • {file:./relative/or/absolute/path}: inject file content
Notes:
  • Relative {file:...} paths resolve from the config file’s directory.
  • ~ is supported in file references.
  • Commented references are ignored.

​
Environment variables

Frequently used flags:
  • ZEROXZERO_CONFIG: explicit config file path
  • ZEROXZERO_CONFIG_DIR: explicit extension directory (.zeroxzero-style)
  • ZEROXZERO_CONFIG_CONTENT: inline JSON config override
  • ZEROXZERO_DISABLE_PROJECT_CONFIG: disable project config loading
  • ZEROXZERO_PERMISSION: inline JSON permission override
  • ZEROXZERO_SERVER_USERNAME / ZEROXZERO_SERVER_PASSWORD: server basic auth
  • ZEROXZERO_AUTO_SHARE: auto-share override
  • ZEROXZERO_DISABLE_AUTOCOMPACT, ZEROXZERO_DISABLE_PRUNE: compaction overrides
  • ZEROXZERO_DISABLE_AUTOUPDATE: disable auto-update checks
There are additional experimental flags in packages/0x0/src/flag/flag.ts.

​
Troubleshooting

  • Show resolved config: 0x0 debug config
  • Show paths: 0x0 debug paths
  • Check models: 0x0 models --refresh
  • Check MCP status: 0x0 mcp list and 0x0 mcp auth list
  • Run without TUI: 0x0 run "diagnose this repo" --format json