Commands — Nyzhi Docs

The Nyzhi binary is called nyz. It operates in three modes: interactive TUI, non-interactive run, and CI/scripting exec.

Three Execution Modes

Command	Mode	Best for
`nyz`	Interactive TUI	Daily development, exploring code, iterating
`nyz run "..."`	Non-interactive	One-shot tasks with human-readable output
`nyz exec "..."`	CI/Scripting	Automation, pipelines, JSON event streams

`nyz` — Interactive TUI

Launch the full terminal interface:

nyz

Resume a previous session:

nyz --continue                    # most recent session
nyz --session "refactor auth"     # by title or ID

`nyz run` — Non-Interactive

Run a single prompt and get human-readable output:

nyz run "add error handling to src/api.rs"
nyz run -i screenshot.png "what's wrong with this UI?"
nyz run --format json "stream events as JSONL"
nyz run -o result.md "summarize the codebase"

Options:

Flag	Description
`-i`, `--image <path>`	Attach an image (repeatable)
`--format <text\|json>`	Output format (default: `text`)
`-o`, `--output <file>`	Write final response to file

`nyz exec` — CI/Scripting

Designed for automation. Supports stdin, ephemeral mode, and sandbox control:

nyz exec "fix lint errors"
cat ci.log | nyz exec --json "explain this failure"
nyz exec --sandbox read-only --ephemeral "audit this repository"
nyz exec --full_auto "update dependencies and run tests"

Options:

Flag	Description
`-i`, `--image <path>`	Attach an image (repeatable)
`--json`	Output JSONL event stream
`-q`, `--quiet`	Suppress non-essential output
`--ephemeral`	Don’t save the session
`--full_auto`	Auto-approve everything + workspace-write sandbox
`--sandbox <level>`	`read-only`, `workspace-write`, or `full-access`
`-o`, `--output <file>`	Write final response to file

Note: If no prompt is provided and stdin isn’t piped, exec exits with an error.

Differences Between `run` and `exec`

Behavior	`run`	`exec`
Sandbox	Full access	`workspace-write` (default)
Session persistence	Always	Optional (`--ephemeral`)
Auto-approve mode	No	Yes (`--full_auto`)
Stdin support	No	Yes
JSON output	Via `--format json`	Via `--json`

Global Flags

These work with any mode:

Flag	Description
`-p`, `--provider <id>`	Override the default provider
`-m`, `--model <name>`	Override the model
`-y`, `--trust <mode>`	Override trust mode (`off`, `limited`, `autoedit`, `full`)
`-c`, `--continue`	Resume the most recent session
`-s`, `--session <query>`	Resume a session by title or ID
`--team-name <name>`	Set team context (agent becomes team lead)

Auth Commands

The preferred interactive auth path is /connect inside the TUI:

nyz
/connect

CLI fallback commands:

nyz login              # interactive provider picker
nyz login openai       # log in to specific provider
nyz logout anthropic   # remove stored credentials
nyz whoami             # show auth status for all providers

Config and Init

nyz config             # print merged runtime config
nyz init               # scaffold .nyzhi/ in current project
nyz deepinit           # advanced project initialization

MCP Management

nyz mcp add fs -- npx @modelcontextprotocol/server-filesystem .
nyz mcp add api --url https://mcp.example.com/sse --scope global
nyz mcp list
nyz mcp remove fs --scope project

Session Management

nyz sessions                            # list recent sessions
nyz sessions "auth"                     # search by keyword
nyz session rename "old" "New Title"    # rename
nyz session delete "old experiment"     # delete
nyz export "auth refactor" -o review.md # export to markdown
nyz replay <session-id>                 # replay event timeline
nyz replay <id> --filter tool_call      # filtered replay

Analytics

nyz stats              # usage statistics
nyz cost               # cost breakdown
nyz cost daily         # daily costs (aliases: day)
nyz cost weekly        # weekly costs (aliases: week)
nyz cost monthly       # monthly costs (aliases: month)

Teams and Skills

nyz teams list          # list all teams
nyz teams show backend  # show team details
nyz teams delete old    # delete a team
nyz skills              # list available skills

CI and Maintenance

# Fix CI failures automatically
nyz ci-fix --log-file ci.log --format junit
nyz ci-fix --commit              # auto-commit the fix
cat ci.log | nyz ci-fix          # pipe from stdin

# Self-update
nyz update
nyz update --force
nyz update --rollback latest
nyz update --list-backups

# Uninstall
nyz uninstall
nyz uninstall --yes              # skip confirmation

Exit Codes

Code	Meaning
`0`	Success
Non-zero	Validation error, missing input, or ambiguous query

For automation, use nyz exec --json for machine-readable event output.

Next Steps

Getting Started — first steps
Configuration — customize behavior
Hooks — event-driven automation