Skip to content

YAMS CLI Reference

A practical, task-focused reference for the yams command-line interface.

This document covers global flags, environment variables, and each subcommand with usage notes and examples. It is structured so tools can extract command-specific sections.

For help:

  • yams --help - Show all available commands
  • yams <command> --help - Show command-specific help

Synopsis

yams [OPTIONS] <command> [command-options]

Environment Variables

Precedence: explicit CLI flags > configuration file > environment variables > defaults

  • YAMS_STORAGE - Storage root directory when --data-dir is not provided and config does not set core.data_dir
  • XDG_DATA_HOME - Default storage location (~/.local/share if unset)
  • XDG_CONFIG_HOME - Default config location (~/.config if unset)
  • HOME - Fallback when XDG paths are not set

Global Options

  • --data-dir, --storage <path> - Override storage root (default: $XDG_DATA_HOME/yams)
  • --json - Output in JSON format where supported
  • -v, --verbose - Enable verbose output
  • --version - Display program version
  • -h, --help - Print help message

Commands

Core Operations

  • init - Initialize YAMS storage and configuration
  • add - Add document(s) or directory to content store
  • get - Retrieve a document from content store
  • cat - Display document content to stdout
  • delete, rm - Delete documents by hash, name, or pattern
  • list, ls - List stored documents
  • update - Update metadata for existing document

Search & Discovery

  • search - Search documents by query (semantic + keyword)
  • grep - Search for regex patterns within file contents with an rg-compatible flag subset
  • graph - Inspect knowledge graph relationships, path/tree structure, and topology

Collections & Snapshots

  • restore - Restore documents from collections/snapshots to filesystem
  • diff - Compare two snapshots and show file changes

System Management

  • daemon - Manage YAMS daemon process (start/stop/restart/status)
  • doctor - Diagnose system health, connectivity, and repair issues
  • status - Show quick system status and health overview
  • stats - Show detailed system statistics
  • config - Manage YAMS configuration settings

Advanced Features

  • model - Download and manage ONNX embedding models
  • plugin, plugins - Manage plugins (list/scan/load/unload/trust)
  • session - Manage interactive session selectors and warming
  • watch - Enable session-based auto-ingest for a project
  • download - Download artifacts and store directly into YAMS
  • repair - Repair and maintain storage integrity

User Interface

  • serve - Start MCP (Model Context Protocol) server
  • completion - Generate shell completion scripts (bash/zsh/fish/powershell)

Utilities

init

Initialize YAMS storage and configuration (interactive or non-interactive).

Synopsis:

  • yams init [OPTIONS]

Options:

  • –non-interactive
  • Run without prompts, using defaults and passed flags.
  • –auto
  • Run setup with defaults for headless environments.
  • –force
  • Overwrite existing config/keys if already initialized.
  • –no-keygen
  • Skip authentication key generation.
  • –print
  • Print resulting configuration to stdout (secrets masked).
  • –enable-plugins
  • Create and trust a local plugins directory (~/.local/lib/yams/plugins).

Notes:

  • The storage directory can be set globally via –storage/–data-dir or YAMS_STORAGE.
  • On first run, initialization will create the storage directory, database, and configuration.
  • Interactive mode prompts for optional model, grammar, and agent-skill setup.
  • Init also bootstraps a per-project session (scoping + watch).
  • Use yams watch to enable auto-ingest for existing projects.

Examples:

# Interactive initialization
yams init

# Auto mode for headless environments
yams init --auto

# Non-interactive with explicit storage
yams --storage "$HOME/.local/share/yams" init --non-interactive

# Force re-initialization
yams init --force

# Print config without secrets
yams init --print

watch

Enable or disable session-based auto-ingest for a project.

Synopsis:

  • yams watch [OPTIONS]
  • yams watch –stop [OPTIONS]

Options:

  • –start
  • Enable watch (default)
  • –stop
  • Disable watch
  • –interval
  • Set polling interval in milliseconds
  • –root
  • Project root to watch (default: git root or cwd)
  • –session
  • Session name (default: auto)
  • –no-use
  • Do not set the session as current
  • –no-selector
  • Do not add the project root as a session selector
  • –daemon-ready-timeout-ms
  • Max time to wait for daemon readiness (0 to skip)

Notes:

  • If the session does not exist, yams watch creates it and sets watch settings.
  • If no root is provided, the git root is used when available.
  • yams watch waits for daemon readiness by default to avoid ingesting while the daemon is still initializing.

Examples:

# Enable watch for the current project (auto session)
yams watch

# Use a 5s polling interval
yams watch --interval 5000

# Disable watch
yams watch --stop

# Explicit root and session
yams watch --root . --session my-project

add

Manual indexing (when watch is disabled) Use YAMS to index code updates if auto-ingest is not enabled.

Examples:

# Index entire source tree (initial import)
yams add src/ --recursive --include="*.cpp,*.hpp,*.h" --tags "code,source"
yams add include/ --recursive --include="*.hpp,*.h" --tags "code,headers"

# Re-index after local edits (quick pass)
yams add . --recursive --include="*.cpp,*.hpp,*.h,*.md" --tags "code,working"

# Add a single updated file
yams add path/to/file.cpp --tags "code,source"

# Update metadata for an existing document by name
yams update --name path/to/file.cpp --metadata "updated=$(date -Iseconds)"

Tips:

  • Prefer comma-separated patterns with –include for multiple file types.
  • Tag code consistently (e.g., code,source; code,headers) to improve later queries.

Add a document to the store from a file or stdin.

Synopsis:

  • yams add [options]
  • yams add [options]
  • yams add - [options] # read from stdin

Options:

  • -n, –name
  • Set the document name (especially useful for stdin input)
  • -t, –tags
  • Comma-separated tags for the document (repeatable)
  • -m, –metadata
  • Custom metadata key-value pairs (repeatable)
  • –mime-type
  • Override MIME type detection
  • –no-auto-mime
  • Disable automatic MIME type detection
  • –no-embeddings
  • Disable automatic embedding generation for added documents
  • -r, –recursive
  • Recursively add files from directories
  • –include
  • File patterns to include (e.g., ‘.txt,.md’)
  • –exclude
  • File patterns to exclude (e.g., ‘.tmp,.log’)
  • -c, –collection
  • Collection name for organizing documents
  • –snapshot-id
  • Unique snapshot identifier
  • –snapshot-label
  • Human-readable label for the automatic snapshot (optional)
  • –verify
  • Verify stored content (hash + existence) after add; slower but safer
  • –global, –no-session
  • Add to global memory (bypass active session)

Description:

  • Ingests the specified file or standard input and stores it in the content-addressed store.
  • Rich metadata support for tagging, naming, and custom properties.
  • Content is automatically indexed for full-text and fuzzy search.
  • Automatic snapshots (snapshot improvements): Every yams add operation automatically creates a snapshot with a timestamp-based ID (e.g., 2025-10-01T14:30:00.123Z). A Merkle tree is built and stored for efficient diff operations.
  • Invocation-level snapshot consistency: A single yams add command invocation reuses one snapshot ID across all provided inputs (multiple files, stdin, and directories) unless --snapshot-id is explicitly set.
  • Snapshot listing parity: Non-directory adds (single file/stdin) are also persisted into tree_snapshots, so yams list --snapshots reflects both directory and non-directory snapshot operations.
  • Trees enable fast yams diff operations using O(log n) subtree matching.
  • Git integration: When run in a git repository, snapshot metadata includes the current commit hash and branch name.

Examples:

# Basic document addition (automatic snapshot created)
yams add ./README.md
# → Snapshot: 2025-10-01T14:30:00.123Z

# Add with human-friendly label
yams add . --recursive --snapshot-label "Release 1.0"
# → Snapshot: 2025-10-01T14:30:00.456Z (label: "Release 1.0")

# Organize by collection
yams add docs/ --recursive --collection=documentation
# → Snapshot: 2025-10-01T14:30:01.789Z (collection: "documentation")

# Standard operations (all create automatic snapshots)
cat notes.txt | yams add - --name "meeting-notes" --tags "work,meeting"
yams add document.pdf --tags "research,papers" --metadata "author=John Doe"
yams add src/ --recursive --include="*.cpp,*.h" --tags "code,source"

Automatic Snapshot Workflows:

  1. Initial import (automatic snapshot):
yams add . --recursive --include="*.cpp,*.h,*.md" --snapshot-label "Initial import"
# → Snapshot: 2025-10-01T09:00:00.000Z
  1. After making changes (automatic snapshot):
yams add . --recursive --include="*.cpp,*.h,*.md" --snapshot-label "Added new feature"
# → Snapshot: 2025-10-01T14:30:00.000Z
  1. Compare any two snapshots:
# List all snapshots to find IDs
yams list --snapshots

# Compare using timestamp IDs
yams diff 2025-10-01T09:00:00.000Z 2025-10-01T14:30:00.000Z
  1. View snapshot timeline:
yams list --snapshots
# Shows chronological list of all automatic snapshots

Performance Notes:

  • Tree building adds ~5-10% overhead to yams add but enables O(log n) diff operations.
  • Trees are stored once in CAS and deduplicated across snapshots.
  • For large repositories (>10K files), tree-based diff is 10-100x faster than flat comparison.
  • Automatic snapshots have zero mental overhead - just use yams add normally.

get

Retrieve a document by hash or name for downloading.

Synopsis:

  • yams get [options]
  • yams get –name [options]

Options:

  • –name
  • Retrieve document by name instead of hash
  • -o, –output
  • Write output to specified file instead of stdout
  • -v, –verbose
  • Enable verbose output
  • –graph
  • Show related documents from knowledge graph
  • –depth
  • Depth of graph traversal, 1-5 (default: 1)

Description:

  • Downloads content by hash or name.
  • For viewing content directly, use the cat command instead.
  • Supports both stdout redirection and explicit output file specification.

Examples:

yams get abcd1234... -o output.txt
yams get --name "document.pdf" -o restored.pdf
yams get --name "config.json" > config.json
yams get abcd1234... --verbose

graph

Show related documents, symbols, and source context from the knowledge graph (read-only).

Synopsis:

  • yams graph [–depth N]
  • yams graph –name [–depth N]
  • yams graph –explore [–max-files N]

Options:

  • –explore
  • Build agent-oriented graph context: ranked symbols, relationships, and line-numbered snippets.
  • –max-files
  • Maximum files to include in --explore output.
  • –name
  • Resolve the target by path/name instead of hash.
  • –depth
  • Depth of graph traversal, 1-5 (default: 1).
  • -v, –verbose
  • Verbose header details.

Description:

  • --explore is the preferred follow-up from search/grep hints when an agent needs source context.
  • Traditional hash/name/node traversal mirrors the graph view available in get --graph without fetching content.
  • Uses knowledge-graph symbol metadata where available and falls back to warnings when source snippets cannot be read.

Examples:

yams graph --explore "processTask" --max-files 3
yams graph --explore "src/app/services/search_service.cpp"
yams graph 0123abcd... --depth 2
yams graph --name "docs/readme.md" --depth 3

cat

Display document content to stdout.

Synopsis:

  • yams cat
  • yams cat –name

Options:

  • –name
  • Display document by name instead of hash

Description:

  • Outputs content directly to stdout for viewing or piping.
  • Silent operation - no status messages (ideal for piping).
  • Use get command for downloading files.

Examples:

yams cat abcd1234...
yams cat --name "notes.txt"
yams cat --name "config.json" | jq .
yams cat --name "script.sh" | bash

delete

rm

Delete documents by hash, name, or pattern. (Alias: rm)

Synopsis:

  • yams delete [options]
  • yams delete –name [options]
  • yams delete –names [options]
  • yams delete –pattern [options]

Options:

  • –name
  • Delete a document by its name
  • –names
  • Delete multiple documents by names (comma-separated)
  • –pattern
  • Delete documents matching a glob pattern (e.g., .log, temp_.txt)
  • –force, –no-confirm
  • Skip confirmation prompt
  • –dry-run
  • Preview what would be deleted without actually deleting
  • –keep-refs
  • Keep reference counts (don’t decrement)
  • -v, –verbose
  • Show detailed deletion progress

Description:

  • Supports deletion by hash (original behavior), name, multiple names, or pattern matching.
  • When deleting by name and multiple documents have the same name, you’ll be prompted to confirm unless –force is used.
  • Pattern matching supports standard glob patterns (* for any characters, ? for single character).
  • Dry-run mode shows what would be deleted without making changes.
  • Bulk deletions show progress and report both successes and failures.

Examples:

# Delete by hash (original)
yams delete abcd1234...
yams rm abcd1234...  # Using alias

# Delete by name
yams delete --name "meeting-notes.txt"
yams rm --name "old-file.txt" --force  # Using alias

# Delete multiple files
yams delete --names "old-report.pdf,draft.txt,temp.log"

# Delete by pattern
yams delete --pattern "*.tmp"
yams delete --pattern "backup_*.zip" --dry-run

# Force deletion without confirmation
yams delete --pattern "temp_*" --force

# Verbose output
yams delete --names "file1.txt,file2.txt" --verbose

list

ls

List stored documents with rich metadata display. (Alias: ls)

Synopsis:

  • yams list [options]

Options:

  • –format
  • Output format: table | json | csv | minimal (default: table)
  • -l, –limit
  • Maximum number of documents to list (default: 100)
  • –offset
  • Offset for pagination (default: 0)
  • –recent
  • Show N most recent documents
  • –sort
  • Sort by: name | size | date | hash (default: date)
  • -r, –reverse
  • Reverse sort order
  • -v, –verbose
  • Show detailed information
  • –show-snippets
  • Show content previews (default: true)
  • –show-metadata
  • Show all metadata for each document
  • –show-tags
  • Show document tags (default: true)
  • –snippet-length
  • Length of content snippets (default: 50)
  • –no-snippets
  • Disable content previews

Description:

  • Displays documents with names, types, sizes, content snippets, and timestamps.
  • Rich table format shows stable NAME, TYPE, SIZE, SNIPPET, and WHEN columns.
  • By default, a compact detail line shows tags plus key metadata (owner, source) under each row when present.
  • --show-metadata expands detail lines to include all metadata keys.
  • The –recent flag filters to the N most recent documents before applying other sorting options.
  • Content snippets provide quick previews of document contents.
  • Multiple output formats support different use cases from human-readable to machine processing.
  • JSON output separates metadata and tags (tags are an array, metadata excludes tag keys).
  • --show-metadata prints metadata even without --verbose for table output.

Examples:

yams list
yams ls  # Using alias
yams list --recent 10  # Show 10 most recent documents
yams list --sort size --reverse  # Sort by size, largest first
yams list --format json
yams ls --format csv --limit 50  # Using alias
yams list --format minimal --offset 20
yams list --no-snippets --show-metadata  # No previews, full metadata
yams list --format json --show-metadata | jq '.documents[] | {name,metadata,tags}'

Tree-Based Query Optimization (v0.7.5+)

The list command uses tree-based path indexing for efficient queries on large repositories. Path patterns with wildcards (*, **) automatically leverage tree structures for O(log n) performance:

Pattern-based queries (tree-optimized):

# List all documents under docs/ directory (recursive)
yams list --name "docs/**"

# List all markdown files in src/
yams list --name "src/**/*.md"

# List all files in a specific directory (non-recursive)
yams list --name "project/bin/*"

Combining patterns with filters (tree query + filtering):

# Documents under docs/ with specific tag
yams list --name "docs/**" --tags "api"

# C++ source files under src/ with multiple tags
yams list --name "src/**/*.cpp" --tags "code,reviewed"

# All text files under project/ by MIME type
yams list --name "project/**" --mime "text/plain"

# Files by extension under specific path
yams list --name "examples/**" --extension ".json"

# Combined filters for precise results
yams list --name "src/**" --tags "test" --extension ".cpp" --mime "text/x-c++"

Performance notes:

  • Tree queries with path prefixes: ~160 μs per query (6.25k queries/sec)
  • Tree queries with filters: 100-126 μs per query (up to 10k queries/sec)
  • Filters can improve performance by reducing result set size
  • Use /** for recursive directory matching, /* for single-level
  • Patterns are automatically canonicalized on macOS to handle /var → /private/var symlinks

Best practices:

  • Prefer tree-based patterns (path/**) over substring matches for better performance
  • Combine multiple filters to narrow results efficiently
  • Use --format json with tree queries for programmatic processing

Snapshot Operations (Enhanced in snapshot improvements)

The list command has been enhanced with smart snapshot and file history capabilities:

List all snapshots:

yams list --snapshots
yams list --snapshots --format json
yams list --snapshots --collection myproject

Show file history across snapshots:

# Shows timeline of changes (Added, Modified, Renamed) across all snapshots
yams list src/main.cpp

# Output example:
# File: src/main.cpp
# 
# Snapshot History:
# v1.2  2025-10-01 14:30  Modified  hash: abc123...  2.5 KB  (current)
# v1.1  2025-09-22 10:15  Modified  hash: def456...  2.3 KB  
# v1.0  2025-09-15 09:00  Added     hash: ghi789...  2.1 KB

Show file at specific snapshot:

yams list src/main.cpp --snapshot-id=v1.0

# Output shows metadata and suggests next actions:
# File: src/main.cpp (v1.0)
# Size: 2.1 KB
# Hash: ghi789...
# 
# Use 'yams cat src/main.cpp --snapshot-id=v1.0' to view content
# Use 'yams list src/main.cpp' to see history across all snapshots

Compare file between snapshots (inline diff):

yams list src/main.cpp --snapshot-id=v1.0 --compare-to=v1.1

# Shows inline diff with syntax highlighting:
# File: src/main.cpp
# Comparing: v1.0 → v1.1
# 
# @@ -10,6 +10,8 @@
#  int main(int argc, char** argv) {
# +    // Initialize logging
# +    initLogger();
#      processArgs(argc, argv);
#      return runApp();
#  }

Smart behavior:

  • yams list → List all documents
  • yams list --snapshots → List all available snapshots
  • yams list <directory> → List indexed descendants under that directory (default --limit 100, use --offset to paginate)
  • yams list <pattern-with-*-or-?> → Treat input as a list pattern, including absolute path globs
  • yams list <filepath> → Show file history across snapshots when the input resolves to a file or historical path
  • yams list <filepath> --snapshot-id=X → Show file at snapshot X
  • yams list <filepath> --snapshot-id=X --compare-to=Y → Inline diff

The command classifies inputs by meaning instead of just checking for / or ..

diff

Compare two snapshots and show file changes with tree diff.

New in snapshot improvements: Efficient snapshot comparison using Merkle tree diffs with rename detection.

Synopsis:

  • yams diff [options]

Options:

  • –format
  • Output format: tree (default) | flat | json
  • tree: Structured diff with rename detection (recommended)
  • flat: Legacy flat diff without rename tracking
  • json: Machine-readable output for tools
  • –include
  • Include only files matching patterns (comma-separated globs)
  • Example: –include=”.cpp,.h”
  • –exclude
  • Exclude files matching patterns (comma-separated globs)
  • Example: –exclude=”.log,.tmp,build/**”
  • –type
  • Filter by change type: added | deleted | modified | renamed
  • Example: –type=modified (show only modified files)
  • –stats
  • Show only summary statistics (no file list)
  • –no-renames
  • Disable rename detection (faster, but less accurate)
  • -v, –verbose
  • Show detailed information including file hashes

Description:

  • Compares two snapshots and displays changes using efficient tree diff algorithm.
  • Rename detection: Automatically detects moved/renamed files by matching content hashes.
  • O(log n) subtree matching: Unchanged subtrees are skipped for performance.
  • Changes are grouped by type: Added, Deleted, Modified, Renamed, Moved.
  • Tree format is the default and recommended for most use cases.

Examples:

# Basic diff
yams diff v1.0 v1.1

# Output example:
# Comparing v1.0 → v1.1
# 
# Added (6 files):
#   + src/new-feature.cpp
#   + src/new-feature.h
#   + tests/test_new_feature.cpp
#   + docs/new-feature.md
#   + lib/dependency.so
#   + config/feature-flags.json
# 
# Deleted (2 files):
#   - src/deprecated.cpp
#   - src/deprecated.h
# 
# Modified (3 files):
#   ~ src/main.cpp                 (2.3 KB → 2.5 KB)
#   ~ README.md                     (1.1 KB → 1.3 KB)
#   ~ Makefile                      (845 B → 920 B)
# 
# Renamed (1 file):
#   → src/utils.cpp → src/common/utils.cpp
# 
# Summary:
#   +6 files added
#   -2 files deleted
#   ~3 files modified
#   →1 file renamed
#   Total: 12 changes

# Filter by file type
yams diff v1.0 v1.1 --include="*.cpp,*.h"

# Show only modified files
yams diff v1.0 v1.1 --type=modified

# Show summary statistics only
yams diff v1.0 v1.1 --stats

# Output example (stats):
# Snapshot Comparison: v1.0 → v1.1
#   Files added:    6
#   Files deleted:  2
#   Files modified: 3
#   Files renamed:  1
#   Total changes:  12

# JSON output for tools
yams diff v1.0 v1.1 --format=json

# Legacy flat diff (convenience flag)
yams diff v1.0 v1.1 --flat-diff
# Or equivalently:
yams diff v1.0 v1.1 --format=flat

# Compare specific directory
yams diff v1.0 v1.1 --include="src/**"

# Exclude build artifacts
yams diff v1.0 v1.1 --exclude="build/**,*.o,*.so"

# Verbose output with hashes
yams diff v1.0 v1.1 -v

Performance Notes:

  • Tree diff is computed in O(log n) time when trees are pre-built during yams add.
  • If trees don’t exist, they will be computed on-demand (may be slower for large snapshots).
  • Use --no-renames to skip rename detection for faster results on very large diffs.

See Also:

  • yams list --snapshots - List available snapshots
  • yams list <file> - Show file history across snapshots
  • yams add --snapshot-id - Create snapshots

Note: Default search type is hybrid. When strict/hybrid returns zero results, the CLI auto-retries with fuzzy (similarity 0.7).

YAMS-first code search Always use YAMS to search the indexed codebase (no external grep/find/rg).

Notes:

  • If results are empty, ensure the repo is indexed (yams add ...) and the daemon is ready (yams status).
  • Scope searches to the repo with --cwd or --path when multiple projects share a storage.

Examples:

# List only file paths for efficient context
yams search "IndexingPipeline" --paths-only

# Fuzzy search for broader discovery
yams search "vector database" --fuzzy --similarity 0.7 --paths-only

# Restrict by extension via keyword filters
yams search "class DocumentIndexer ext:.cpp" --paths-only

# Show JSON for scripting
yams search "SyncManager" --json

# Queries that start with '-' (option-looking) — pass safely
yams search -q "--start-group --whole-archive --end-group -force_load Darwin" --paths-only
yams search -- "--start-group --whole-archive --end-group -force_load Darwin" --paths-only
printf '%s\n' "--start-group --whole-archive --end-group -force_load Darwin" | yams search --stdin --paths-only
yams search --query-file /tmp/query.txt --paths-only
yams search --query-file - --paths-only < /tmp/query.txt

Hints:

  • Prefer hybrid or fuzzy search for exploratory queries; narrow with exact keywords as you iterate.
  • Combine with –paths-only to feed subsequent yams get calls.
  • Session helpers (experimental): Use yams session add|list|rm-path|warm to manage hot data. See PROMPT docs for examples: ../PROMPT-eng.md and ../PROMPT.md

Search for documents with advanced query capabilities.

Synopsis:

  • yams search “” [options]
  • yams search -q “” [options]
  • yams search –stdin [options]
  • yams search –query-file [options]

Options:

  • -q, –query
  • Provide the query as an option (useful when it starts with ‘-‘)
  • –stdin
  • Read query from standard input when no query is provided
  • –query-file
  • Read query from a file path (use ‘-’ to read from stdin)
  • -l, –limit
  • Maximum number of results to return (default: 20)
  • -t, –type
  • Search type: keyword | semantic | hybrid (default: hybrid)
  • -f, –fuzzy
  • Enable fuzzy search for approximate matching
  • –similarity
  • Minimum similarity for fuzzy search, 0.0-1.0 (default: 0.7)
  • –hash
  • Search by file hash (full or partial, minimum 8 characters)
  • -n, –line-numbers
  • Show line numbers with matches
  • -A, –after
  • Show N lines after match (default: 0)
  • -B, –before
  • Show N lines before match (default: 0)
  • -C, –context
  • Show N lines before and after match (default: 0)

Description:

  • Supports both exact keyword searches and fuzzy approximate matching.
  • Fuzzy search uses BK-tree indexing for efficient similarity matching with configurable thresholds.
  • Full-text search with FTS5 indexing provides fast document content queries with robust special character handling.
  • Hash search allows finding documents by their SHA256 hash (full 64-character hash or partial prefix).
  • Automatic fallback: if FTS5 query fails (due to special characters), automatically falls back to fuzzy search.
  • Robust query sanitization handles special characters like hyphens, quotes, and operators (e.g., “task-6”, “task 4-“).
  • JSON output includes relevance scores, execution times, and content snippets.
  • Searches document names, content, tags, and metadata fields.
  • Auto-detects hash format: if query looks like a hash (8-64 hex chars), automatically searches by hash.
  • Verbosity control: concise output by default, detailed output with –verbose flag.

Examples:

# Text search
yams search "database performance"
yams search "config file" --fuzzy --similarity 0.6
yams search "meeting notes" --limit 10 --type keyword
yams search "project roadmap" --json

# Hash search
yams search --hash abcd1234ef567890  # Partial hash (minimum 8 chars)
yams search --hash abcd1234ef567890abcd1234ef567890abcd1234ef567890abcd1234ef567890  # Full hash
yams search abcd1234ef567890  # Auto-detected hash search

# Verbose output for detailed information
yams search "query" --verbose
yams search --hash abcd1234 --verbose

grep

Regex across indexed code (YAMS only, hybrid by default) Use YAMS grep for project-wide regex; avoid system utilities for repository queries.

Examples:

# Find class definitions
yams grep "class\\s+IndexingPipeline" --include="**/*.hpp,**/*.cpp"

# Locate TODOs in headers and sources
yams grep "TODO\\b" --include="**/*.hpp,**/*.h,**/*.cpp"

# Search for CLI subcommand declarations
yams grep "##\\s+(watch|git|sync)\\b" --include="**/*.md"

Notes:

  • grep intentionally mirrors common ripgrep muscle memory for core flags: -e/--regexp, -g/--glob, -F/--fixed-strings, -i, -w, -v, -n, -H, --no-filename, -c, -l, -L, -A/-B/-C, -m/--max-count, and --color.
  • Default output is YAMS-rich/LLM-friendly context; use --minimal when you want grep-style compact output.
  • Default mode is hybrid: regex plus semantic suggestions; use –regex-only to disable. Tune with –semantic-limit (default: 10).
  • Semantic suggestions are also shown in -l/–files-with-matches, -L/–files-without-match, –paths-only, and -c/–count modes. Regex counts only reflect text matches.
  • Hot/Cold modes: control behavior via environment variables. For grep, set YAMS_GREP_MODE=hot_only|cold_only|auto (hot uses extracted text cache; cold scans CAS bytes). For list, use YAMS_LIST_MODE, and for retrieval (cat/get), use YAMS_RETRIEVAL_MODE.
  • --include accepts comma-separated globs or repeated usage; -g/--glob is the rg-style alias. Prefer quoting patterns.
  • --live falls back to scanning the working tree when indexed grep has no hits; use --no-live for indexed-only behavior.
  • Scope to the current project with --here, or pass an optional root with --cwd [path].
  • Pair with yams search –paths-only to scope subsequent grep runs.

Search for regex patterns within file contents.

Synopsis:

  • yams grep [paths…] [options]

Options:

  • -A, –after
  • Show N lines after match (default: 0)
  • -B, –before
  • Show N lines before match (default: 0)
  • -C, –context
  • Show N lines before and after match (default: 0)
  • -i, –ignore-case
  • Case-insensitive search
  • -w, –word
  • Match whole words only
  • -v, –invert
  • Invert match (show non-matching lines)
  • -n, –line-numbers
  • Show line numbers
  • -H, –with-filename
  • Show filename with matches
  • –no-filename
  • Never show filename
  • -c, –count
  • Show only count of matching lines
  • -l, –files-with-matches
  • Show only filenames with matches
  • -L, –files-without-match
  • Show only filenames without matches
  • -e, –regexp
  • Explicit pattern option; use this when the pattern starts with - or to avoid positional ambiguity.
  • -g, –glob
  • rg-compatible glob filter; repeatable and merged with –include.
  • –include
  • File patterns to include, comma-separated or repeated.
  • -F, –fixed-strings
  • Treat pattern as literal text, not regex.
  • –minimal
  • Use compact grep-style output instead of the default rich context.
  • –live / –no-live
  • Enable or disable live working-tree fallback after indexed no-hit results.
  • –cwd [path]
  • Scope grep to a directory. With no value, scopes to the current working directory.
  • –here
  • Scope grep to the current working directory.
  • –color
  • Color mode: always, never, auto (default: auto)
  • –max-count
  • Stop after N matches per file. This matches ripgrep’s per-file -m/--max-count behavior and is not a global result cap.
  • –limit
  • Compatibility alias for –max-count; it is also a per-file match cap, unlike search --limit and list --limit.

Description:

  • Searches through the content of all indexed files using regular expressions.
  • Supports standard grep-like options for context, case sensitivity, and output control.
  • Automatically highlights matches when outputting to a terminal.
  • Can search all indexed files or specific paths.
  • Uses ECMAScript regex syntax for pattern matching.

Examples:

# Basic pattern search
yams grep "TODO"
yams grep "error.*failed" -i

# With context
yams grep "function" -C 2
yams grep "class.*Repository" -A 5

# File listing
yams grep "deprecated" -l
yams grep "test" src/ -c

# Complex patterns
yams grep "^import.*from" -n
yams grep "\bclass\s+\w+Command\b" --color=always

config

Manage YAMS configuration settings.

Subcommands:

  • get
  • Print a configuration value.
  • set
  • Update a configuration value.
  • list
  • Print all keys/values.
  • validate [–config-path ]
  • Validate configuration.
  • export [–format toml|json]
  • Output current configuration.
  • embeddings
  • Manage embedding configuration (model, dimensions).
  • search
  • Manage search configuration.
  • grammar
  • Manage tree-sitter grammars for symbol extraction.
  • tuning
  • Manage daemon tuning settings.
  • storage
  • Configure storage settings.
  • migrate
  • Migrate configuration to v3.
  • update
  • Add newly introduced v3 keys without overwriting existing values.
  • check
  • Check if config needs migration.

Examples:

yams config list
yams config get core.data_dir
yams config set embeddings.preferred_model all-MiniLM-L6-v2
yams config validate
yams config export --format json
yams config grammar list              # List available grammars
yams config grammar download cpp      # Download C++ grammar

stats

Show storage statistics and health.

Synopsis:

  • yams stats [options]

Description:

  • Adaptive default view: when relevant, includes Recommendations and Service Status along with the compact footer; use -v for full System Health and detailed sections.
  • Telemetry includes auto-repair counters (repair_queue_depth, repair_batches_attempted, repair_embeddings_generated, repair_failed_operations), latency percentiles (p50/p95), top_slowest components, and not_ready flags.
  • Use –json for machine-readable output.

Examples:

yams stats
yams stats -v
yams stats --json

update

Update metadata for existing documents.

Synopsis:

  • yams update –metadata …
  • yams update –name –metadata …

Options:

  • hash
  • Document hash (full or partial) to update
  • –name
  • Document name to update (useful for stdin documents)
  • -m, –metadata
  • Metadata key-value pairs to set (can be specified multiple times)
  • -v, –verbose
  • Show detailed update information

Notes:

  • Either hash or –name must be specified, but not both
  • Multiple metadata pairs can be updated in a single command
  • Existing metadata values will be overwritten
  • Works with both file-based and stdin documents
  • If multiple documents have the same name, you’ll be prompted to use the hash

Examples:

# Update by hash
yams update fc8fc5fa --metadata "status=completed" --metadata "reviewed=true"

# Update by name  
yams update --name "project-notes.md" --metadata "priority=high"

# Update stdin document
yams update --name "arxiv-2402.05391" --metadata "read=true" --metadata "rating=5"

# Task tracking example
yams update --name "task-001.md" --metadata "status=in_progress" --metadata "assignee=alice"

model

Manage embedding models: list installed, download new, inspect, and verify runtime.

Synopsis:

  • yams model list
  • yams model download [–url ]
  • yams model info
  • yams model check

Description:

  • list: Shows locally available models (autodiscovers ~/.yams/models//model.onnx and other configured roots)
  • download: Fetches a model by name; use –url to override with a custom ONNX URL
  • info: Prints details for a model (dimensionality, path, notes when available)
  • check: Verifies ONNX runtime support, plugin directory status, and autodiscovery paths

Configuring the preferred model:

  • yams config embeddings model # sets embeddings.preferred_model
  • embeddings.model_path can point to the models root; name-based resolution order: configured root → ~/.yams/models → models/ → /usr/local/share/yams/models

Examples:

yams model list
yams model download all-MiniLM-L6-v2
yams model download my-custom --url https://example.com/models/custom.onnx
yams model info all-MiniLM-L6-v2
yams model check
yams config embeddings model all-MiniLM-L6-v2

plugin

Manage plugins: scanning, trust policy, load/unload, install, and info.

Synopsis:

  • yams plugin list
  • yams plugin scan [–dir DIR] [TARGET]
  • yams plugin info
  • yams plugin health
  • yams plugin load
  • yams plugin unload
  • yams plugin trust add | list [–details] | remove | reset | status
  • yams plugin install
  • yams plugin uninstall
  • yams plugin update [name]
  • yams plugin repo [query]
  • yams plugin search

Subcommands:

  • list: Show loaded plugins and their interfaces.
  • scan: Inspect directories for plugins without initializing; prints name/version/ABI.
  • info: Show manifest/health JSON for a loaded plugin.
  • health: Show health status of loaded plugins.
  • load: Load a plugin by absolute path or name; respects trust policy.
  • unload: Unload a plugin by name.
  • trust: Manage plugin trust and discovery status. Canonical trust file is <data_dir>/plugins.trust (default ~/.local/share/yams/plugins.trust).
  • install: Install plugin from repository or URL.
  • uninstall: Uninstall a plugin.
  • update: Update plugins to latest version.
  • repo: Query plugin repository.
  • search: Search plugin catalog (local index.json).
  • enable/disable: Enable/disable plugins (stub).
  • verify: Verify plugin signature/hash (stub).

Notes:

  • Default discovery roots: persisted trusted paths plus built-in defaults ($HOME/.local/lib/yams/plugins, /opt/homebrew/lib/yams/plugins on macOS, /usr/local/lib/yams/plugins, /usr/lib/yams/plugins, ${CMAKE_INSTALL_PREFIX}/lib/yams/plugins). Strict mode (YAMS_PLUGIN_DIR_STRICT=1 or daemon.plugin_dir_strict=true) disables built-in defaults.
  • The daemon prefers host-backed model_provider_v1 when an ONNX plugin is trusted/loaded; otherwise it falls back to the legacy registry or mock/null provider.
  • Disable plugin subsystem: start the daemon with --no-plugins.

Examples:

# Discover and trust a system plugins directory
yams plugin scan
yams plugin trust add /usr/local/lib/yams/plugins
yams plugin trust list
yams plugin trust status
yams plugin trust reset

# Load ONNX plugin by path (respects trust policy)
yams plugin load /usr/local/lib/yams/plugins/libyams_onnx_plugin.so

# Check plugin health
yams plugin health

# Inspect and unload
yams plugin info onnx
yams plugin unload onnx

doctor

Diagnose daemon connectivity, model/provider readiness, vector DB dimensions, and plugins. Includes repair helpers.

Synopsis:

  • yams doctor [OPTIONS]
  • yams doctor daemon
  • yams doctor plugin []
  • yams doctor plugins
  • yams doctor embeddings
  • yams doctor repair [–embeddings] [–fts5] [–graph] [–all]
  • yams doctor validate
  • yams doctor dedupe
  • yams doctor prune
  • yams doctor tuning

Subcommands:

  • daemon: Check daemon socket and status
  • plugin: Check a specific plugin (.so/.wasm or by name)
  • plugins: Show plugin summary (loaded + scan)
  • embeddings: Embeddings diagnostics and actions
  • repair: Repair common issues (embeddings, FTS5, graph)
  • validate: Validate knowledge graph health
  • dedupe: Detect (and optionally remove) duplicate documents
  • prune: Remove build artifacts, logs, cache, temporary files, and git artifacts
  • tuning: Auto-configure [tuning] based on system baseline

Options:

  • –json: Output results in JSON format
  • –fix: Fix everything (embeddings + FTS5)
  • –fix-config-dims: Align config embedding dims to target (non-interactive)
  • –recreate-vectors: Drop and recreate vector tables to target dim
  • –dim : Target dimension to use with –recreate-vectors
  • –stop-daemon: Attempt to stop daemon before DB operations

Highlights:

  • Summary shows daemon status, vector DB dimension vs model target, and loaded plugins.
  • Knowledge Graph section appears when available; if empty, recommends: yams doctor repair --graph to build from tags/metadata.

Repair options:

  • –embeddings: Generate missing document embeddings (daemon streaming when available; local fallback).
  • –fts5: Rebuild the text index best-effort.
  • –graph: Construct/repair the knowledge graph from tags/metadata.
  • –all: Run all repair operations.

Examples:

yams doctor
yams doctor --json
yams doctor plugin onnx
yams doctor plugins
yams doctor repair --graph
yams doctor repair --all
yams doctor --recreate-vectors --dim 768 --stop-daemon
yams doctor dedupe --dry-run
yams doctor prune
yams doctor tuning

repair

Run storage/database maintenance and (optionally) embedding generation.

Synopsis:

  • yams repair [OPTIONS]

Options:

  • –orphans: Clean orphaned metadata entries
  • –chunks: Remove orphaned chunk files and reclaim space
  • –mime: Fix missing MIME types in documents
  • –fts5: Rebuild FTS5 index for documents (best-effort)
  • –embeddings: Generate missing vector embeddings
  • –checksums: Verify and repair checksums
  • –duplicates: Find and optionally merge duplicates
  • –downloads: Repair download documents (add tags/metadata, normalize names)
  • –path-tree: Rebuild path tree index for documents missing from the tree
  • –optimize: Vacuum/optimize the database
  • –all: Run all repair operations
  • –dry-run: Preview operations without making changes
  • –force: Skip confirmations
  • –foreground: Run embeddings repair in foreground (stream progress)
  • –include-mime : Additional MIME types to embed (e.g., application/pdf), repeatable
  • –model : Embedding model to use (overrides preferred)
  • –stop-daemon: Attempt to stop daemon before vector DB operations
  • -v, –verbose: Show detailed progress

Notes:

  • By default, embedding repair targets text-like MIME types only; binaries (PDFs/images) are skipped unless explicitly included with –include-mime.
  • PDF text extraction and embedding depend on build configuration (PDF support must be available).

Examples:

yams repair --all --dry-run
yams repair --orphans --chunks --optimize --force
yams repair --embeddings
yams repair --embeddings --include-mime application/pdf
yams repair --fts5 --verbose
yams repair --path-tree

status

Show service readiness, subsystem health, and runtime stats (daemon-aware).

Synopsis:

  • yams status

Description:

  • Prints a concise services summary (e.g., ✓ Content | ✓ Repo | ✓ Search | ⚠ (N) Models)
  • During initialization, shows a WAIT line with not-ready components and progress
  • Exposes fields such as running/ready state, uptime, request counts, active connections, memory, CPU, and version when available
  • Highlights top slowest components and actionable recommendations when relevant

Tips:

  • Use yams stats -v for detailed system health, recommendations, and service status sections.
  • Bootstrap status file: ~/.local/state/yams/yams-daemon.status.json

Examples:

yams status

daemon

Control the background daemon (if included in your build).

Synopsis:

  • yams daemon start
  • yams daemon stop
  • yams daemon status
  • yams daemon restart

Description:

  • start/stop/restart the daemon process
  • status shows readiness and subsystem overview similar to yams status

Notes:

  • When client/daemon protocol versions differ, a one-time warning may be shown; upgrade the daemon if features appear limited.
  • Runtime mode selection supports socket and embedded in-process transports.
  • Set YAMS_EMBEDDED=1|true|on|yes to force in-process mode, 0|false|off|no to force socket mode, or auto to probe.
  • Config fallback: [daemon].mode = "embedded" | "socket" | "auto".

Examples:

yams daemon status
yams daemon restart

serve

Start the MCP (Model Context Protocol) server over stdio.

Synopsis:

  • yams serve [OPTIONS]

Options:

  • –daemon-socket
  • Override daemon socket path (env: YAMS_DAEMON_SOCKET)
  • –verbose
  • Show startup banner and enable info-level logging (default: quiet mode)

Description:

  • Exposes YAMS functionality through the Model Context Protocol for AI tool integration.
  • Uses stdio transport (JSON-RPC over stdin/stdout) for direct AI integration.
  • Provides search, retrieval, and document management capabilities to AI systems.
  • Graceful shutdown on SIGINT/SIGTERM signals.
  • Server runs quietly by default; use –verbose for startup banner.

Examples:

# Start MCP server (default quiet mode)
yams serve

# With verbose logging
yams serve --verbose

# With custom daemon socket
yams serve --daemon-socket /tmp/yams.sock

completion

Generate shell completion scripts for popular shells.

Synopsis:

  • yams completion bash
  • yams completion zsh
  • yams completion fish
  • yams completion powershell

Notes:

  • Bash: if bash-completion isn’t installed, a minimal fallback is baked into the script.
  • Zsh: the generated script auto-runs compinit if needed to prevent “_arguments: command not found”.
  • Fish: installs via standard fish completions.
  • PowerShell: uses Register-ArgumentCompleter for native tab completion.

Installation Instructions

Bash (Linux/macOS):

# Quick use without installing
source <(yams completion bash)

# Install for current user
mkdir -p ~/.local/share/bash-completion/completions
yams completion bash > ~/.local/share/bash-completion/completions/yams

# Or install system-wide (requires sudo)
yams completion bash | sudo tee /etc/bash_completion.d/yams > /dev/null

Note: Homebrew installs the bash completion file, but your shell still needs bash-completion startup support enabled.

Zsh (Linux/macOS):

# Quick use without installing
autoload -U compinit && compinit
source <(yams completion zsh)

# Install for current user (Oh My Zsh)
yams completion zsh > ~/.oh-my-zsh/completions/_yams

# Or standard location
mkdir -p ~/.local/share/zsh/site-functions
yams completion zsh > ~/.local/share/zsh/site-functions/_yams

# Ensure the install directory is on fpath before compinit runs
fpath=(~/.local/share/zsh/site-functions $fpath)
autoload -U compinit && compinit

The generated completions now support nested subcommands and nested leaf values such as:

  • yams config embeddings ...
  • yams doctor embeddings ...
  • yams plugin trust ...
  • yams plugins trust ... (alias of plugin)
  • yams daemon start --log-level <Tab>
  • yams config search path-tree enable --mode <Tab>

Fish:

yams completion fish > ~/.config/fish/completions/yams.fish

If you are not using Homebrew’s fish package, make sure your fish_complete_path includes the directory where the completion file is installed.

PowerShell (Windows/Linux/macOS):

# Quick use for current session
Invoke-Expression (yams completion powershell | Out-String)

# Install permanently (add to profile)
yams completion powershell | Out-File -Encoding utf8 $PROFILE.CurrentUserAllHosts -Append

# Or create a separate completion file
$completionPath = "$HOME\.config\yams\completions"
New-Item -ItemType Directory -Path $completionPath -Force
yams completion powershell | Out-File -Encoding utf8 "$completionPath\yams.ps1"
# Then add to your profile: . "$HOME\.config\yams\completions\yams.ps1"

Verifying Installation

After installing, restart your shell or reload your profile:

# Bash
source ~/.bashrc   # or ~/.zshrc

# PowerShell
. $PROFILE

For zsh, make sure compinit runs after your fpath updates.

Then test by typing one of these and pressing Tab:

yams plugin trust 
yams plugins trust 
yams daemon start --log-level 
yams config search path-tree enable --mode

Symbol Extraction

YAMS extracts functions, classes, imports, and calls from source files via tree-sitter grammars managed under yams config grammar.

yams config grammar list                        # available + installed
yams config grammar download cpp python rust    # fetch specific grammars
yams add src/ --recursive --include="*.cpp,*.py,*.rs"   # symbols extracted on add

Supported languages (18): C, C++, C#, Dart, Go, Java, JavaScript, Kotlin, P4, Perl, PHP, Python, R, Rust, Solidity, SQL, TypeScript, Zig.

Source of truth: plugins/symbol_extractor_treesitter/symbol_extractor.cpp (language_configs).

Pin an existing grammar manually with YAMS_TS_<LANG>_LIB=/path/to/libtree-sitter-<lang>.so (e.g. YAMS_TS_CPP_LIB). Requires git + a C compiler when grammars are built locally.

Exit Codes

  • 0 Success.
  • 1 General error (unexpected exception or failure).
  • Non-zero values may indicate specific errors depending on the subcommand.

Snapshot Workflows

New in snapshot improvements: Efficient snapshot management with Merkle tree diffs and rename detection.

Overview

Snapshots provide point-in-time captures of your repository content. YAMS automatically builds Merkle trees during yams add --snapshot-id operations, enabling fast O(log n) diff comparisons between snapshots.

Basic Workflow

1. Initial import (automatic snapshot):

# Capture current state of source code
yams add . --recursive \
  --include="*.cpp,*.hpp,*.h,*.md" \
  --snapshot-label "Initial release" \
  --tags "code,release"

# Snapshot created automatically: 2025-10-01T09:00:00.000Z

2. Make changes to your codebase:

# Edit files, add features, fix bugs...
vim src/main.cpp
git commit -am "Added new feature"

3. Capture updated state (automatic snapshot):

# Just add again - snapshot created automatically
yams add . --recursive \
  --include="*.cpp,*.hpp,*.h,*.md" \
  --snapshot-label "Feature release" \
  --tags "code,release"

# New snapshot: 2025-10-01T14:30:00.000Z

4. Compare snapshots:

# List snapshots to find timestamp IDs
yams list --snapshots

# Compare using timestamp IDs (fast O(log n) tree diff)
yams diff 2025-10-01T09:00:00.000Z 2025-10-01T14:30:00.000Z

# Output example:
# Comparing v1.0 → v1.1
# 
# Added (3 files):
#   + src/new-feature.cpp
#   + src/new-feature.h
#   + tests/test_new_feature.cpp
# 
# Modified (2 files):
#   ~ src/main.cpp                 (2.3 KB → 2.5 KB)
#   ~ README.md                     (1.1 KB → 1.3 KB)
# 
# Renamed (1 file):
#   → src/utils.cpp → src/common/utils.cpp
# 
# Summary: 6 changes (+3, ~2, →1)

Snapshot Discovery

List all snapshots:

yams list --snapshots

# Output example (chronological, newest first):
# Snapshot ID                  Label              Collection      Files  Date
# 2025-10-01T14:30:00.000Z    Feature release    -               125    2025-10-01 14:30
# 2025-09-20T10:15:00.000Z    Updated docs       documentation    45    2025-09-20 10:15
# 2025-09-15T09:00:00.000Z    Initial release    -               122    2025-09-15 09:00

Filter by collection:

yams list --snapshots --collection=releases

JSON output for tools:

yams list --snapshots --format=json | jq '.[] | select(.label | contains("release"))'

File History Tracking

View file history across snapshots:

yams list src/main.cpp

# Output example:
# File: src/main.cpp
# 
# Snapshot History:
# v1.1  2025-10-01 14:30  Modified  hash: abc123...  2.5 KB  (current)
# v1.0  2025-09-15 09:00  Added     hash: def456...  2.3 KB

View file at specific snapshot:

# See metadata
yams list src/main.cpp --snapshot-id=v1.0

# View content
yams cat src/main.cpp --snapshot-id=v1.0

# Restore to disk
yams get --name src/main.cpp --snapshot-id=v1.0 -o main-v1.0.cpp

Inline diff between snapshots:

yams list src/main.cpp --snapshot-id=v1.0 --compare-to=v1.1

# Shows inline diff with syntax highlighting

Advanced Diff Operations

Filter by file type:

# Show only C++ changes
yams diff v1.0 v1.1 --include="*.cpp,*.hpp"

# Exclude build artifacts
yams diff v1.0 v1.1 --exclude="build/**,*.o"

Filter by change type:

# Show only added files
yams diff v1.0 v1.1 --type=added

# Show only renames (useful for tracking file moves)
yams diff v1.0 v1.1 --type=renamed

Summary statistics:

yams diff v1.0 v1.1 --stats

# Output:
# Snapshot Comparison: v1.0 → v1.1
#   Files added:    3
#   Files deleted:  0
#   Files modified: 2
#   Files renamed:  1
#   Total changes:  6

JSON output for tools:

yams diff v1.0 v1.1 --format=json > diff.json

# Analyze with jq:
jq '.changes[] | select(.type == "modified")' diff.json

Verbose output with hashes:

yams diff v1.0 v1.1 -v

# Shows full file hashes for each change

Collections and Organization

Organize snapshots by collection:

# Development snapshots
yams add src/ --recursive --collection=dev --snapshot-id=dev-2025-10-01

# Documentation snapshots
yams add docs/ --recursive --collection=documentation --snapshot-id=docs-v3

# Release snapshots
yams add . --recursive --collection=releases --snapshot-id=v2.0 --snapshot-label="Major release"

Compare within collections:

yams list --snapshots --collection=releases
yams diff v1.0 v2.0  # Compare releases

Restoration Workflows

Restore entire snapshot:

# Restore to specific directory
yams restore --snapshot-id=v1.0 --output=./restore-v1.0

# Preview without writing files
yams restore --snapshot-id=v1.0 --output=./test --dry-run

# Overwrite existing files
yams restore --snapshot-id=v1.0 --output=. --overwrite

Selective restoration:

# Restore only specific file types
yams restore --snapshot-id=v1.0 \
  --output=./restore \
  --include="*.cpp,*.h"

# Exclude directories
yams restore --snapshot-id=v1.0 \
  --output=./restore \
  --exclude="build/**,third_party/**"

Restore by collection:

yams restore --collection=releases --output=./releases

Performance Characteristics

Tree-based diff performance:

  • Small changes (< 1%): O(log n) subtree matching, ~100x faster than flat diff
  • Large changes (> 50%): Approaches O(n) but still faster due to hash-based comparison
  • Rename detection: Hash-based matching is O(n) but only runs on Added/Deleted pairs

Storage efficiency:

  • Merkle trees are stored once in CAS and deduplicated across snapshots
  • Unchanged subtrees share the same tree hash (deduplication)
  • Tree overhead: ~5-10% additional storage for large repositories
  • Diff computation: ~5-10% slower during yams add --snapshot-id (tree building)

Optimization tips:

  • Use --exclude patterns to skip build artifacts, caches, and temporary files
  • Use --no-renames for faster diff when rename tracking isn’t needed
  • Pre-build trees during snapshot creation for instant diff operations

Integration with Git

Automatic git integration: When yams add runs in a git repository, snapshot metadata automatically includes:

  • git_commit: Current commit hash (e.g., abc123def456)
  • git_branch: Current branch name (e.g., main, develop)
  • git_remote: Remote repository URL (if configured)

This creates a natural bidirectional link between YAMS snapshots and git history.

Snapshot on git commit (hook):

#!/bin/bash
# Hook: .git/hooks/post-commit
# Automatically snapshot on every commit
yams add . --recursive \
  --include="*.cpp,*.hpp,*.h,*.md" \
  --snapshot-label "$(git log -1 --pretty=%B | head -1)" \
  --tags "code,git,auto"

Snapshot on git tag:

#!/bin/bash
# Hook: .git/hooks/post-tag
TAG=$(git describe --tags --abbrev=0)
yams add . --recursive \
  --include="*.cpp,*.hpp,*.h,*.md" \
  --snapshot-label="Git tag: $TAG" \
  --tags "code,git,release"

Daily snapshots:

#!/bin/bash
# Cron: daily snapshot at midnight
yams add . --recursive \
  --include="*.cpp,*.hpp,*.h,*.md" \
  --snapshot-label="Daily backup" \
  --tags "code,daily"
# Snapshot ID is auto-generated with current timestamp

Troubleshooting

Missing trees:

# If diff is slow, trees may not exist
# Rebuild trees for existing snapshots (not yet exposed via CLI).
# Re-run yams add to regenerate trees as needed.

Large diff output:

# Use filters to reduce output
yams diff v1.0 v2.0 --type=modified --include="src/**"
yams diff v1.0 v2.0 --stats  # Summary only

Restore conflicts:

# Preview first
yams restore --snapshot-id=v1.0 --output=./test --dry-run

# Use overwrite cautiously
yams restore --snapshot-id=v1.0 --output=. --overwrite

Best Practices

  1. Use labels liberally: Labels make snapshot timelines human-readable (--snapshot-label "Before refactor")
  2. Leverage automatic IDs: No need to manually manage snapshot IDs - timestamps provide natural ordering
  3. Exclude build artifacts: Use --exclude="build/**,*.o,*.so" to reduce noise and improve performance
  4. Tag meaningful snapshots: Use --tags for filtering (e.g., release, milestone, backup)
  5. Collections for organization: Group related content (--collection=releases, --collection=docs)
  6. Automate with git hooks: Snapshot on every commit or tag for complete history tracking
  7. Test restores: Verify snapshots with --dry-run before overwriting files
  8. Trust the timestamps: Snapshot IDs are ISO 8601 timestamps - sort naturally and are globally unique

download

Download an artifact and store it into YAMS, or manage daemon-tracked download jobs.

Synopsis:

  • yams download <url> [options]
  • yams download --status <job-id> [--json]
  • yams download --list-jobs [--json]
  • yams download --cancel <job-id> [--json]

Options:

  • <url>
  • Artifact URL to download.
  • --checksum <algo:hex>
  • Expected checksum. This is strongly recommended for direct downloads and may be required by daemon policy.
  • --status <job-id>
  • Show the current state of a daemon-managed download job.
  • --list-jobs
  • List tracked daemon download jobs.
  • --cancel <job-id>
  • Cancel a daemon-managed download job.
  • --json
  • Emit structured output for direct download results or job/status queries.

Description:

  • Default behavior is store-only: downloaded content is verified and finalized into YAMS CAS.
  • The daemon path is policy-gated and disabled by default.
  • When daemon download is enabled, accepted requests are backgrounded as tracked jobs.
  • Current daemon job control supports:
  • start via yams download <url>
  • status
  • list-jobs
  • cancel
  • The daemon path is intentionally narrow:
  • HTTPS-style allowlist policy is expected
  • store-only behavior is enforced
  • checksum policy may reject requests before network activity
  • arbitrary export paths, custom headers, proxy overrides, and broader transport tuning are not part of the daemon job surface

Notes:

  • The daemon feature gate is YAMS_ENABLE_DAEMON_DOWNLOAD.
  • A successful daemon-backed start returns a jobId; use that with --status or --cancel.
  • cancel is cooperative: the job transitions to canceled, and active downloader work is asked to stop.
  • Resume-by-job is not implemented yet; current downloader resume behavior is still internal to the downloader layer.

Examples:

# Direct store-only download
yams download "https://example.com/archive.tar.gz" --checksum sha256:<hex>

# Start a daemon-managed download when the feature is enabled
YAMS_ENABLE_DAEMON_DOWNLOAD=1 yams download "https://example.com/archive.tar.gz" --checksum sha256:<hex> --json

# Check daemon job status
yams download --status job-123 --json

# List tracked daemon download jobs
yams download --list-jobs

# Cancel a running daemon download job
yams download --cancel job-123

Tips

YAMS-first workflow

  • Always search the codebase with YAMS (search/grep). Do not use system grep/find/rg for repository queries.
  • Enable auto-ingest with yams watch when possible; otherwise re-index with yams add.
  • Use –paths-only for path lists you can pipe into further commands or editors.
  • Prefer –include with comma-separated patterns (e.g., “.cpp,.hpp,*.h”) to bound searches and indexing.
  • Retrieve exact files for review with yams get –name -o .

  • Keep tags consistent (e.g., code,source; code,headers; code,working) and update metadata with yams update as needed.

  • Use –json where supported to integrate with scripts and tools.

  • Specify a storage directory explicitly with –storage or via YAMS_STORAGE to keep data separate for testing vs production.
  • When available, use –help –verbose for detailed per-command help, or yams –help-all for the full reference in the terminal.