Getting Started

Install Nyzhi, set an API key, and run your first task in under two minutes.

TL;DR

curl -fsSL https://get.nyzhi.com | sh
export OPENAI_API_KEY="sk-..."
nyz run "Add unit tests for the parse_config function"

Installation

Choose one method. The curl script is recommended for most users.

curl (recommended)

curl -fsSL https://get.nyzhi.com | sh

Downloads the latest release, verifies the SHA256 hash, and installs nyz to ~/.nyzhi/bin/. Add that directory to your PATH if it isn’t already.

Cargo

cargo install nyzhi

Requires Rust. Installs from crates.io.

npm

npx nyzhi
# or install globally:
npm install -g nyzhi

Use npx nyzhi for a one-off run without installing. Use npm install -g nyzhi to add nyz to your PATH.

Homebrew

brew install nyzhi

From source

git clone https://github.com/nyzhi/nyzhi && cd nyzhi && cargo build --release

The binary is at target/release/nyz. See Building for full build instructions.

Verify install

nyz --version

Example output:

nyzhi 0.x.x

Connect a provider

Nyzhi needs credentials for at least one LLM provider.

Option A: /connect (Recommended)

The fastest way. Launch Nyzhi and use the built-in provider selector:

nyz

Then type:

/connect

This opens an interactive picker where you choose a provider, authenticate via OAuth (when available), or paste an API key. Done — you’re connected.

Option B: Environment variable

Set the provider’s env var before running Nyzhi:

export OPENAI_API_KEY="sk-..."
# Or: export ANTHROPIC_API_KEY="sk-ant-..."
# Or: export DEEPSEEK_API_KEY="sk-..."
# Or: export GEMINI_API_KEY="AI..."

Tip: Add the export to your shell profile (~/.bashrc, ~/.zshrc) so you don’t have to set it every time.

Option C: CLI login

For providers that support OAuth, log in from the command line — no raw API key needed:

nyz login openai
nyz login anthropic
nyz login gemini

Tokens are stored locally. See Authentication for the full flow.

Option D: Config file

Store the key in your config:

# ~/.config/nyzhi/config.toml

[provider]
default = "openai"

[provider.openai]
model = "gpt-4o"
api_key = "sk-..."

Warning: Config files can be read by other processes. Prefer /connect or environment variables for sensitive keys.

Quick provider reference

See Providers for the full list and model options.

Run your first task

From a project directory:

nyz run "Add unit tests for the parse_config function"

Nyzhi will read the codebase, locate parse_config, write tests, run them, and report the results. Output streams to stdout.

Example output:

> nyz run "Add unit tests for the parse_config function"

Reading src/config.rs...
Editing src/config.rs...
Writing tests/config_test.rs...
Running: cargo test
   Compiling my-project v0.1.0
    Finished test [unoptimized + debuginfo]
     Running unittests src/main.rs
running 3 tests
test config::tests::parse_config_valid ... ok
test config::tests::parse_config_empty ... ok
test config::tests::parse_config_invalid ... ok
test result: ok. 3 passed; 0 failed; 0 ignored

Initialize a project

Create a project-specific config and directory structure:

nyz init

This creates:

• .nyzhi/ — Project config directory
• .nyzhi/config.toml — Project settings (optional, created if you add config)
• .nyzhi/commands/ — Custom slash commands (optional)

You can also run /init from the TUI. See Configuration for what goes in .nyzhi/config.toml.

Interactive TUI basics

Launch the interactive terminal UI:

nyz

In a project directory, Nyzhi detects the workspace and loads project rules (e.g., from .nyzhi/ or AGENTS.md).

Typing prompts: Type your task and press Enter. The agent responds with text and tool calls. You can approve or deny tool execution depending on trust mode.

Slash commands: Type / to see available commands. Common ones:

Use Tab to autocomplete slash commands and @-mentioned file paths. See TUI for the full reference.

Trust modes

Trust mode controls whether tools that modify files or run commands need your approval before execution.

Recommendation: Start with off or limited until you’re comfortable. Use limited with allow_tools = ["edit", "write"] and allow_paths = ["src/", "tests/"] for a balanced workflow.

Set via TUI: /trust limited. Or in config:

[agent.trust]
mode = "limited"
allow_tools = ["edit", "write"]
allow_paths = ["src/", "tests/"]

See Configuration for full trust settings.

Next Steps

• Configuration — Global, project, and local TOML settings
• Providers — Connect OpenAI, Anthropic, Gemini, DeepSeek, Ollama, and more
• Tools — 50+ built-in tools for files, git, shell, and code analysis
• TUI — Slash commands, shortcuts, theming, and session management