Schemap CLI Reference & Safety Guide

Install Schemap globally on your workstation using pipx or uv:

# Recommended: Install globally via pipx
pipx install schemap-tool

# Or using uv
uv tool install schemap-tool

# Upgrade to latest version anytime
pipx upgrade schemap-tool

Runs the interactive onboarding pipeline: auto-detects local SQLite databases and environment connection strings, creates schemap.yaml, compiles context, installs agent rules, and prints an AI Readiness Summary Card.

schemap quickstart

# Non-interactive mode with specific database URL
schemap quickstart --non-interactive --db "sqlite:///examples/demo_ecommerce.db"

Initializes a new schemap.yaml configuration asset in the current working directory.

schemap init
schemap init --full   # Generate full configuration boilerplate

Compiles token-optimized database context files. Supports Markdown, JSON, YAML, XML, MCP, AI-prompt, and Mermaid ER diagram formats.

schemap context
schemap context --format mermaid     # Generate Mermaid ER diagram (erDiagram)
schemap context --format json        # Export machine-readable JSON context

Generates CLAUDE.md, AGENTS.md, and .cursor/rules/schemap.mdc files for AI coding agents. Uses safe marker preservation (<!-- schemap:start -->) to protect user-authored notes.

schemap agents --targets codex,claude,cursor
schemap agents --dry-run               # Preview output without modifying files
schemap agents --diff                  # Show unified git-style diff of changes
schemap agents --force                 # Force overwrite existing files

Calculates a SHA256 database schema structure fingerprint. Regenerates context maps and agent files ONLY when the schema structure actually changes.

schemap sync
schemap sync --force   # Force sync even if schema fingerprint is unchanged

Runs AI Database Health Check. Emits actionable remediation objects: inferred foreign key candidates with confidence scores (e.g. 95%), unresolved abbreviation mappings, and configuration snippets.

schemap doctor
schemap doctor --json   # Output health check report in machine-readable JSON

Interactively prompts user to accept or reject inferred foreign key relationships and abbreviation mappings, automatically persisting accepted fixes back into schemap.yaml.

schemap fix --interactive
schemap fix --accept-all   # Auto-accept all inferred FK candidates and mappings

Calculates the 0-100 AI Readiness Score for the schema based on primary keys, foreign key connectivity, documentation coverage, and naming consistency.

schemap score

Extracts database metadata and displays a clean structural summary of tables, columns, foreign keys, and indexes.

schemap inspect
schemap inspect --json

Explains table architecture, primary keys, column data types, descriptions, incoming references, and centrality scores.

schemap explain table orders
schemap explain table users --json

Uses Breadth-First Search (BFS) over foreign key relationships to find the shortest joining path between tables and outputs a valid SQL JOIN clause.

schemap join users orders payments

# Output snippet:
# SELECT *
# FROM users
# JOIN orders ON users.id = orders.user_id
# JOIN payments ON orders.id = payments.order_id;

Compares current schema against tracked state. Supports --json diff output and --fail-on-breaking for CI pipeline gates.

schemap diff
schemap diff --json
schemap diff --fail-on-breaking   # Exit status code 2 if breaking changes exist

Global options supported across all Schemap CLI commands:

schemap --profile staging context
schemap --quiet doctor
schemap --no-color score

Installs agent-native schemap AI skills for Codex, Claude Code, and Cursor. Decoupled from specific database facts so project rules stay in AGENTS.md.

schemap skills install --targets codex,claude,cursor

# Installed skill paths:
#   .codex/skills/schemap/SKILL.md
#   .claude/skills/schemap/SKILL.md
#   .cursor/rules/schemap.mdc

Complete configuration file options including named profiles and foreign key overrides:

# Schemap Configuration Asset
database:
  connection_url: "sqlite:///examples/demo_ecommerce.db"
  exclude_tables:
    - "spatial_ref_sys"

output:
  file_path: "./schemap_database_context.md"
  format: "markdown"

domain:
  mappings:
    cust: "Customer"
    tx: "Transaction"

# Manual/inferred foreign key overrides
foreign_key_overrides:
  - table: "orders"
    column: "user_id"
    ref_table: "users"
    ref_column: "id"

# Named environment profiles
profiles:
  staging:
    database:
      connection_url: "postgresql://user:pass@staging-db:5432/mydb"
  production:
    database:
      connection_url: "postgresql://user:pass@prod-db:5432/mydb"