<!-- source: https://deepwiki.com/qhkm/zeptoclaw/4.1-command-structure -->

# Command Structure

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

This page documents the overall CLI architecture of ZeptoClaw, including the argument parsing framework, command dispatch mechanism, and common patterns used across all commands.

## Architecture Overview

ZeptoClaw's CLI is built on the `clap` crate using derive macros for declarative argument parsing. The architecture follows a three-tier structure:

1. Top-level parser — The Cli struct defines the entry point and version metadata src/cli/mod.rs 40-47
2. Command enum — The Commands enum enumerates all available subcommands with their arguments src/cli/mod.rs 49-271
3. Dispatch handlers — Individual modules implement command logic, called by cli::run() src/cli/mod.rs 525-670

### CLI Entity Mapping

The following diagram maps high-level CLI concepts to their specific implementation entities in the codebase.

Title: CLI Entity Mapping

```

```

Sources: [src/cli/mod.rs40-271](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L40-L271) [src/cli/agent.rs116-159](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L116-L159) [src/cli/config.rs11-16](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L11-L16) [src/cli/slash.rs89-99](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/slash.rs#L89-L99)

## Command Parsing and Dispatch

The CLI uses a declarative approach where command structure is defined through Rust types and `clap` derive attributes. The `main.rs` entry point calls `cli::run()`, which performs the following sequence:

1. Logging Init : Loads configuration to initialize the logging system src/cli/mod.rs 526-532
2. Parsing : Uses Cli::parse() to process std::env::args() src/cli/mod.rs 534
3. Dispatch : Matches the resulting Commands variant and calls the associated handler function src/cli/mod.rs 537-668

Title: Command Execution Data Flow

```

```

Sources: [src/cli/mod.rs537-668](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L537-L668) [src/cli/config.rs11-16](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L11-L16) [src/cli/onboard.rs17-111](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L17-L111)

## Top-Level Commands Reference

The `Commands` enum defines the primary interface for ZeptoClaw.

Sources: [src/cli/mod.rs49-271](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L49-L271)

## Common Argument Patterns

### Global Context and Defaults

ZeptoClaw CLI commands frequently resolve the current working directory as the default workspace to ensure relative paths in tool calls (like `read_file`) function as expected by the user [src/cli/agent.rs128-132](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L128-L132)

### Template Resolution

Commands like `agent` and `batch` support a `--template` flag. This logic uses `resolve_template()` to look up JSON definitions in `~/.zeptoclaw/templates/` or built-in defaults [src/cli/agent.rs142-146](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L142-L146)

### Interactive Approval

For security, the CLI implements a standard approval prompt in `prompt_cli_approval`. This blocks execution and waits for user confirmation (y/N) before sensitive tools are executed [src/cli/agent.rs67-105](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L67-L105)

### Visual Feedback (Shimmer)

Interactive commands utilize a "Shimmer" spinner to indicate active LLM thinking [src/cli/agent.rs166-186](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L166-L186) It provides real-time feedback on tool execution phases:

- Thinking : LLM is generating a response src/cli/agent.rs 179-181
- Starting : Tool call initiated src/cli/agent.rs 187-199
- Done : Successful execution with timing src/cli/agent.rs 201-213

Title: CLI Feedback Loop

```

```

Sources: [src/cli/agent.rs166-213](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L166-L213)

## Configuration Validation Structure

The `config check` command performs deep inspection of the configuration file using a diagnostic system.

- Schema Validation : Checks for unknown fields at the top level src/config/validate.rs 204-222 and within nested sections like agents.defaults src/config/validate.rs 225-240
- Levenshtein Suggestions : Provides "did you mean?" hints for misspelled configuration keys src/config/validate.rs 118-150
- SSRF Checks : Validates provider API endpoints to prevent SSRF by blocking local/private network targets unless explicitly allowed src/config/validate.rs 155-179
- Custom Tool Validation : Ensures that user-defined shell tools in the config are valid src/cli/config.rs 54-58

Sources: [src/cli/config.rs19-117](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L19-L117) [src/config/validate.rs1-240](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L1-L240)

## Interactive Mode Slash Commands

When running in interactive `agent` mode, the CLI supports "slash commands" for runtime control without restarting the process.

- Registry : Commands are defined in builtin_commands() src/cli/slash.rs 19-86
- Completion : The SlashHelper provides tab-completion for commands like /model , /persona , and /tools src/cli/slash.rs 101-133
- Trust Management : Users can toggle approval bypass for the current session using /trust on and /trust off src/cli/slash.rs 66-76

Sources: [src/cli/slash.rs1-159](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/slash.rs#L1-L159) [src/cli/agent.rs21-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L21-L22)
