<!-- source: https://deepwiki.com/qhkm/zeptoclaw/4-cli-reference -->

# CLI Reference

- src/cli/config.rs
- src/cli/mod.rs
- src/cli/onboard.rs
- src/config/validate.rs

This document provides a comprehensive reference for the ZeptoClaw command-line interface, documenting the commands, options, and execution patterns. It covers the command structure, argument parsing, and dispatch system implemented via the `clap` library.

ZeptoClaw uses a single binary (`zeptoclaw`) with a subcommand-based architecture. All commands are parsed through the `Cli` struct in [src/cli/mod.rs40-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L40-L47) and dispatched via the `run()` function at [src/cli/mod.rs318-421](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L318-L421)

## Command-Line Interface Overview

The CLI supports two primary execution modes:

1. Interactive/Agent mode : Direct interaction with the LLM via terminal.
2. Service/Gateway mode : Running as a background server for multiple communication channels.

**Command Hierarchy and Entity Mapping**

This diagram bridges the Natural Language commands to the specific Rust modules and functions that handle them.

```

```

Sources: [src/cli/mod.rs40-169](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L40-L169) [src/cli/mod.rs318-421](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L318-L421)

## Top-Level Commands

The following table summarizes the primary commands. For detailed technical breakdowns, refer to the linked child pages.

Sources: [src/cli/mod.rs50-235](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L50-L235)

## Execution and Dispatch Flow

The CLI uses a pattern-match dispatch system. The `main.rs` entry point calls `cli::run()`, which initializes logging and matches the parsed subcommand to its respective handler. Interactive sessions utilize `SlashHelper` for command completion and `prompt_cli_approval` for human-in-the-loop security.

**Internal Dispatch Architecture**

```

```

Sources: [src/cli/mod.rs318-421](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L318-L421) [src/cli/gateway.rs27-105](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L27-L105) [src/cli/agent.rs67-105](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L67-L105)

## Logging and Diagnostics

ZeptoClaw utilizes the `tracing` crate for structured logging. Initialization occurs at [src/cli/mod.rs318-333](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L318-L333)

- Filter : Controlled via RUST_LOG (defaults to warn ).
- Format : Controlled via RUST_LOG_FORMAT . Setting this to json enables structured output suitable for production log aggregators src/cli/mod.rs 326-333
- Diagnostics : The doctor command performs health checks on providers and local environment src/cli/mod.rs 222-226
- Validation : The config check command utilizes validate_config to detect unknown fields and provide Levenshtein-based suggestions src/config/validate.rs 143-150

Sources: [src/cli/mod.rs318-333](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L318-L333) [src/cli/mod.rs222-226](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L222-L226) [src/config/validate.rs182-222](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L182-L222)

## Detailed CLI Sections

This reference is split into specialized sub-pages for depth:

### Command Structure

Covers the technical architecture of the CLI, including how `clap` is configured, common argument patterns (like `--template`), and the global `run()` loop.

### Agent Commands

Detailed documentation for `agent`, `batch`, and `agent-stdin`. Includes explanation of streaming, dry-run modes, and the shimmer-based progress feedback system [src/cli/agent.rs166-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L166-L200) Covers `/` slash commands such as `/model` and `/trust` [src/cli/slash.rs19-86](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/slash.rs#L19-L86)

### Gateway Commands

Documentation for the `gateway` command. Covers multi-channel orchestration, the startup guard for crash prevention [src/cli/gateway.rs37-61](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L37-L61) and tunnel integration (Cloudflare, Ngrok).

### Configuration Commands

Reference for `onboard`, `config check`, and the `secrets` management suite. Explains the interactive wizard flow [src/cli/onboard.rs17-111](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L17-L111) and SSRF validation for provider endpoints [src/config/validate.rs155-179](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L155-L179)

### Management Commands

Covers administrative utilities: `memory` for long-term storage, `history` for session management, `tools` for registry inspection, `quota` for provider usage tracking, and `daemon` for supervised service runs.

**Sources:**

- src/cli/mod.rs 40-429
- src/cli/agent.rs 1-200
- src/cli/gateway.rs 27-154
- src/cli/onboard.rs 1-111
- src/cli/slash.rs 1-86
- src/config/validate.rs 1-222
- src/main.rs 1-10
