CLI overview

The nave CLI maps directly onto the lifecycle stages. Each subcommand belongs to exactly one group, and each group corresponds to a state layer.

Command groups

Setup

• nave init — create ~/.config/nave.toml.

Read (data)

• nave scan — enumerate repos; index tracked files.
• nave pull — sparse-checkout tracked files into the cache.

Read (analysis)

• nave search — substring and structural queries.
• nave build — anti-unified templates and hole reports.

Validate

• nave check — parse and round-trip tracked files.
• nave schemas — manage schema cache; validate pens.

Write

• nave pen — pens, subcommands for the full lifecycle.

Global conventions

• --json — most commands support structured output for scripting.
• NAVE_LOG=debug — verbose logging (tracing-subscriber EnvFilter syntax).
• --help on any subcommand prints its usage.

Shared grammar

Two pieces of grammar are used across multiple commands:

• Terms (search, pen create, build --where): [scope:]value[|value...]. See Query language.
• Match predicates (search --match, build --match, pen create --match): [scope:] [!] path [op literal] where op is one of =, !=, ^=, $=, *=. A bare path tests presence; !path tests absence. Paths support [] wildcards for array elements. See Query language § Structural predicates.