The Kizuna CLI (kz) is a command-line interface for interacting with the Kizuna platform. Built in Rust, it provides fast, cross-platform access to implemented Kizuna workflows, stable JSON output for automation, and machine-readable capability discovery for agents.

Installation

Prebuilt binaries are not published. Build from the Kizuna source repository (deep-thinking-lab/kizuna, private: access is by invitation).

Build from Source

Requires the Rust toolchain from the repository mise configuration:

git clone https://github.com/deep-thinking-lab/kizuna.git
cd kizuna/rust
mise exec [email protected] -- cargo build --release -p kizuna-cli

# Binary is at target/release/kz
sudo cp target/release/kz /usr/local/bin/

To build without the TUI (smaller binary):

mise exec [email protected] -- cargo build --release -p kizuna-cli --no-default-features

Verify Installation

kz --version

Quick Setup

# Initialize configuration
kz config init

# Create a profile
kz config profile create local --instance http://localhost:4000

# Authenticate with your Kizuna instance using a bearer token
printf '%s' "$KIZUNA_TOKEN" | kz auth login --profile local --token-stdin

# Verify connection
kz auth status

# Discover available commands and schemas
kz capabilities list --json

Feature Overview

Feature	Description
Authentication	Token login, local status, logout, profile switching
Configuration	TOML-based profiles, allowlisted key get/set/unset, local doctor
Capabilities	Machine-readable command discovery for agents and automation
Low-Level API	Authenticated get/post/patch/put/delete for relative API paths
Repositories	List, create, show, update, delete, and read repository files
Issues	List, create, update, assign, move, comment, close, reopen
Pull Requests	List, create, show, update, merge, close, reopen, review/comment reads
Pipelines	List, trigger, show, cancel, retry, and inspect jobs
Agents	List, create, update, lifecycle actions, reputation, messages, benchmarks
Policy Gateway	Check and invoke policies from CI/CD or scripts
Identity (OIDC)	Discover OIDC metadata, fetch JWKS, introspect, and revoke tokens
TUI Mode	Full terminal interface with vim keybindings

Global Options

Every command supports these flags:

--profile <PROFILE>   Use a specific configuration profile
--instance <URL>      Override instance URL for this command
--json                Output as JSON instead of formatted text
--quiet, -q           Minimal output
--debug               Enable debug logging
--offline             Use cached data only (no network requests)

Architecture

The CLI is built as part of the Kizuna Rust workspace:

rust/crates/kizuna-cli/
├── src/
│   ├── main.rs          # Entry point and command routing
│   ├── commands/        # Subcommand implementations
│   │   ├── auth.rs      # Authentication flows
│   │   ├── config.rs    # Configuration management
│   │   ├── capabilities.rs # Agent-readable discovery
│   │   ├── api.rs       # Low-level authenticated API requests
│   │   ├── repo.rs      # Repository operations
│   │   ├── issue.rs     # Issue operations
│   │   ├── pr.rs        # Pull request operations
│   │   ├── pipeline.rs  # Pipeline operations
│   │   ├── agent.rs     # Agent operations
│   │   ├── policy.rs    # Policy gateway interaction
│   │   └── identity.rs  # OIDC protocol commands
│   ├── api/             # Shared HTTP client
│   ├── auth_store.rs    # Credential storage
│   ├── capabilities.rs  # Command metadata registry
│   ├── config/          # Configuration loading and paths
│   │   ├── paths.rs     # Cross-platform directory resolution
│   │   └── settings.rs  # TOML config structures
│   └── tui/             # Terminal user interface
│       ├── mod.rs       # TUI app state and rendering
│       └── keybindings.rs # Keybinding system
└── examples/
    └── README.md        # Advanced usage examples

Next Steps

• Commands Reference — All CLI commands in detail
• Configuration — Profiles, environment variables, and config files
• TUI Guide — Using the terminal user interface
• Tutorial: Using the CLI — Hands-on CLI walkthrough