Schemap CLI Reference & Safety Guide

Run instantly with zero install via uvx, or install globally:

# 1. Zero install — run grounding directly
uvx schemap-tool@4.0.1 ground "What was total revenue?" --db "sqlite:///saas.db"

# 2. Or install globally on your workstation
uv tool install schemap-tool==4.0.1
pipx install schemap-tool==4.0.1

# 3. Self-update to latest PyPI version anytime
schemap update
schemap update --check   # Check without installing

Generates a deterministic grounding plan for an AI coding agent before it writes SQL. Automatically resolves currency scale (e.g. cents to dollars), multi-hop foreign key join paths, and mandatory invariants (soft-delete filters, tenant isolation).

# Ground prompt with tenant isolation
schemap ground "What was Acme Corp's total paid revenue?" --db "sqlite:///saas.db" --tenant-id 1

# Ground multi-hop join relationships
schemap ground "List every invoice ID and its plan name" --db "sqlite:///saas.db"

Verifies agent-generated SQL against policy rules and tenant invariants. Rejects and intercepts destructive mutations (DELETE, DROP, TRUNCATE) in read/analytics scopes before execution.

# Verify tenant-safe query
schemap verify "SELECT SUM(amount_cents)/100.0 FROM invoices WHERE org_id = 1" --db "sqlite:///saas.db" --tenant-id 1

# Intercept and block dangerous mutations
schemap verify "DELETE FROM users WHERE status = 'inactive'" --db "sqlite:///saas.db"

Launches the Model Context Protocol (MCP) server for Cursor and Claude Code, providing schemap_ground and schemap_verify tool endpoints.

# Launch stdio MCP server directly
uvx schemap-tool@4.0.1 mcp

# In Cursor (.cursor/mcp.json) or Claude Code (claude_desktop_config.json):
# {
#   "mcpServers": {
#     "schemap": {
#       "command": "uvx",
#       "args": ["schemap-tool@4.0.1", "mcp"],
#       "env": { "DATABASE_URL": "postgresql://user:pass@host:5432/dbname" }
#     }
#   }
# }

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

Queries PyPI for the latest published version of schemap-tool, detects your active package manager (uv, pipx, or pip), and performs an automated in-place upgrade.

# Self-upgrade to latest version
schemap update

# Check if a newer version is available without installing
schemap update --check

# Force re-install current version
schemap update --force

Cleanly uninstalls the Schemap CLI package using your detected package manager. Optionally purges stored global credentials, local device identifiers, and license caches.

# Interactive uninstallation (prompts for confirmation)
schemap uninstall

# Non-interactive uninstallation
schemap uninstall --yes

# Complete uninstallation and purge all local credentials/caches
schemap uninstall --yes --purge

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"