<!-- source: https://deepwiki.com/qhkm/zeptoclaw/4.4-configuration-commands -->

# Configuration Commands

- src/cli/config.rs
- src/cli/mod.rs
- src/cli/onboard.rs
- src/cli/secrets.rs
- src/config/validate.rs
- src/security/encryption.rs
- src/security/mod.rs
- src/security/mount.rs
- src/security/path.rs

This page documents the CLI commands for initializing, validating, and managing ZeptoClaw configuration. For runtime configuration structure and hot reload, see [Configuration](/qhkm/zeptoclaw/5-configuration). For environment variable overrides, see [Environment Variable Overrides](/qhkm/zeptoclaw/5.2-environment-variable-overrides).

The configuration command suite includes:

- onboard — Interactive setup wizard for first-time initialization.
- config check — Schema validation with diagnostics and suggestions.
- secrets — Encryption, decryption, and key rotation for sensitive values.
- template — Management of agent personas and system prompts.
- skills — Discovery and installation of markdown-based agent capabilities.
- tools — Discovery and configuration inspection for built-in and opt-in tools.

## Command Overview

All configuration commands operate on the config directory at `~/.zeptoclaw/` (or `$ZEPTOCLAW_CONFIG_DIR`). The primary config file is `config.json` at [src/cli/config.rs20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L20-L20)

## Onboard Command

The `onboard` command provides an interactive wizard to bootstrap the ZeptoClaw environment.

### Code-to-Entity Mapping: Onboarding Logic

The following diagram maps the natural language steps of onboarding to the specific functions in the `onboard.rs` module.

```

```

### Onboarding Modes

- Express Mode : Default behavior when running zeptoclaw onboard . It focuses on setting up the primary LLM provider and API keys src/cli/mod.rs 52-59
- Full Mode : Triggered with --full . It extends the wizard to include steps covering memory backends (BM25, Embedding, HNSW, Tantivy), runtime isolation types (Landlock, Firejail, Docker), and notification channels src/cli/mod.rs 53-55

**Provider Selection**: Users can select Anthropic, OpenAI, or OpenRouter [src/cli/onboard.rs23-27](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L23-L27) The wizard includes a model selection menu that fetches live model IDs from the chosen provider via `configure_model_for_provider`, filtered for chat compatibility using `filter_chat_models` [src/cli/onboard.rs114-141](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L114-L141)

**Sources:** [src/cli/onboard.rs1-111](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/onboard.rs#L1-L111) [src/cli/mod.rs52-59](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L52-L59)

## Config Check and Validation

The `config check` command performs deep inspection of the `config.json` file using a diagnostic engine.

### Diagnostic Engine Data Flow

This diagram illustrates how a raw JSON configuration is transformed into actionable user diagnostics.

```

```

### Validation Features

- Levenshtein Suggestions : If an unknown key is found (e.g., agent instead of agents ), the system calculates the distance using levenshtein() and suggests the correct field via suggest_field() src/config/validate.rs 118-150
- SSRF Protection : validate_network_endpoint() ensures that provider endpoints do not target local/private networks unless explicitly allowed via allow_private_endpoints src/config/validate.rs 155-179
- Tool Validation : validate_custom_tools() checks for naming conflicts in custom_tools and ensures required shell binaries are present src/cli/config.rs 53-58
- Known Fields : The validator maintains an extensive list of KNOWN_TOP_LEVEL and KNOWN_AGENTS_DEFAULTS keys to prevent typos in the config file src/config/validate.rs 11-70

**Sources:** [src/config/validate.rs11-182](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/validate.rs#L11-L182) [src/cli/config.rs19-117](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/config.rs#L19-L117)

## Secrets Management

ZeptoClaw uses `SecretEncryption` to secure API keys and tokens at rest within the JSON configuration.

### Encryption Implementation

- Algorithm : XChaCha20-Poly1305 AEAD src/security/encryption.rs 19
- Key Derivation : Argon2id KDF derives a 256-bit key from a master passphrase src/security/encryption.rs 176-183
- Envelope Format : ENC[version:salt:nonce:ciphertext] src/security/encryption.rs 7-13

### Secrets Commands

The system uses `resolve_master_key()` to prompt the user for the passphrase or retrieve it from environment variables before performing cryptographic operations [src/cli/secrets.rs36](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L36-L36)

**Sources:** [src/security/encryption.rs37-183](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L37-L183) [src/cli/secrets.rs1-173](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L1-L173)

## Template Management

Agent templates encapsulate personas, system prompts, and safety constraints.

### Template Commands

The `Template` subcommand allows managing these definitions [src/cli/mod.rs133-136](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L133-L136)

- list : Shows all available templates (built-in and local).
- info : Displays the system_prompt and tool restrictions for a specific template.
- create : Bootstraps a new template file in ~/.zeptoclaw/templates/ .

### Security and Isolation

Templates play a critical role in security by defining:

- allowed_tools / blocked_tools : Restricting agent capabilities.
- shell_allowlist : Using ShellSecurityConfig to restrict ShellTool to specific binaries src/security/mod.rs 21
- extra_mounts : Validating host-to-container path mapping using validate_extra_mounts() to prevent exposure of sensitive host paths like .ssh or .aws src/security/mount.rs 12-27 src/security/mount.rs 165-215

**Sources:** [src/cli/mod.rs133-136](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L133-L136) [src/security/mount.rs1-215](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mount.rs#L1-L215) [src/security/path.rs70-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/path.rs#L70-L130)
