Evolve CLI¶

Evolve includes a command-line interface for managing namespaces and entities directly.

Installation¶

The CLI is installed automatically with the package:

uv sync

Commands¶

Namespace Management¶

# List all namespaces
evolve namespaces list

# Create a new namespace
evolve namespaces create my_namespace

# Show namespace details
evolve namespaces info my_namespace

# Delete a namespace (prompts for confirmation)
evolve namespaces delete my_namespace

# Delete without confirmation
evolve namespaces delete my_namespace --force

Entity Management¶

# List all entities in a namespace
evolve entities list my_namespace

# List entities filtered by type
evolve entities list my_namespace --type guideline

# Add an entity
evolve entities add my_namespace --content "Always write tests first" --type guideline

# Add entity without LLM-based conflict resolution (faster, no OpenAI key needed)
evolve entities add my_namespace --content "Use descriptive names" --type guideline --no-conflict-resolution

# Add entity with metadata (JSON format)
evolve entities add my_namespace --content "Check return values" --type guideline --metadata '{"source": "code-review"}'

# Search entities using semantic similarity
evolve entities search my_namespace "testing best practices"

# Search with type filter
evolve entities search my_namespace "error handling" --type guideline

# Show full details of an entity
evolve entities show my_namespace 12345

# Delete an entity
evolve entities delete my_namespace 12345

Data Retention¶

# Dry run: report what the policy would flag or delete (nothing is mutated)
evolve retention run --policy retention.yaml

# Sweep a specific namespace
evolve retention run --policy retention.yaml my_namespace

# Enforce the policy
evolve retention run --policy retention.yaml my_namespace --apply

Options: - --policy, -p: Path to a retention policy file (YAML or JSON). Required. - --apply: Actually flag/delete. Without it the run is a dry run. - Positional namespace argument defaults to the configured namespace_id.

The report lists every action with its reason (age, unused, cascade:<trace_id>), the rule that decided it, and the evidence behind it. See the Data Retention guide for the policy format and the AccessStampPlugin dependency of max_unused_days rules.

Skill Management¶

# Package all skills from default location (plugins/evolve/skills → dist/)
evolve skills package

# Preview what would be packaged (no files created)
evolve skills package --dry-run

# Package from a custom source directory
evolve skills package --source ./my-skills

# Package to a custom output directory
evolve skills package --output ./dist

# Remove existing .skill files before packaging
evolve skills package --clean

# Combine options
evolve skills package --source ./my-skills --output ./dist --clean

Options: - --source, -s: Source directory containing skill folders (default: plugins/evolve/skills) - --output, -o: Output directory for .skill files (default: dist) - --clean: Remove existing .skill files in output directory before packaging - --dry-run: Show what would be packaged without creating files

Skill Requirements: - Each skill must be a directory containing a SKILL.md file - The resulting .skill file is a ZIP archive with the skill directory as the top-level folder

Examples¶

# Create a namespace for coding guidelines
uv run evolve namespaces create coding_guidelines

# Add some guidelines
uv run evolve entities add coding_guidelines \
  --content "Always handle errors explicitly" \
  --type guideline \
  --no-conflict-resolution

uv run evolve entities add coding_guidelines \
  --content "Write unit tests for all public functions" \
  --type guideline \
  --no-conflict-resolution

# Search for relevant guidelines
uv run evolve entities search coding_guidelines "error handling"

# List all guidelines
uv run evolve entities list coding_guidelines --type guideline

# Package skills for distribution
uv run evolve skills package --dry-run  # Preview first
uv run evolve skills package --clean    # Package with clean output

Viz¶

# Start the local viz server (opens browser automatically)
evolve viz serve

# Custom .evolve directory and port
evolve viz serve --evolve-dir /path/to/.evolve --port 8080

# Don't open the browser
evolve viz serve --no-browser

Options: - --evolve-dir, -d: Path to .evolve directory (default: .evolve) - --port, -p: Port to serve on (default: 7891) - --no-browser: Skip opening the browser automatically

See the Evolve Viz guide for full usage.

Environment Variables¶

The CLI uses the same environment variables as the MCP server. See the Configuration section in the main README.