CLI Usage

The pretensor CLI is the single entry point. It indexes databases, serves them over MCP, validates queries against the resulting graph, and manages visibility profiles. Run pretensor --help for the live, authoritative listing — the table below is a map of what’s there.

Top-level options

These flags sit before any subcommand and apply to every command in the same invocation.

Flag	Purpose
--config <path>	Path to a CLI YAML config. If omitted, Pretensor looks for .pretensor/config.yaml relative to the working directory. Use this for the global ~/.pretensor/config.yaml pattern (see Connecting your database).
--log-level <level>	One of debug, info, warning, error. Default warning.
--log-format <text|json>	json is useful when piping into log aggregators.
--log-file <path>	Mirror logs to a file in addition to stderr.
--version	Print the installed Pretensor version and exit.

Running bare pretensor with no subcommand and nothing indexed yet prints a one-line hint to run pretensor init before showing help.

Environment variables

Variable	Effect
PRETENSOR_PROFILE_INDEX	When set to anything other than 0/false/no, prints per-stage timing for the indexing pipeline (introspection, graph build, classification, clustering, join-path precompute). Useful when an index run is slower than expected.
PRETENSOR_EMBEDDINGS_DISABLED	Kill switch for embedding features: skips index-time table embeddings and the embedding-backed tool paths even when the embeddings extra is installed.
${VAR} references inside a config file	Resolved by Pretensor at connection time; missing variables raise an explicit error before any database connection is opened.

Subcommands

pretensor quickstart

Boot a throwaway Postgres + Pagila in Docker, index it, and print the mcpServers snippet — the fastest end-to-end smoke test.

Flag	Purpose
--no-docker	Skip the compose step; assumes Postgres is already at postgresql://postgres:postgres@localhost:55432/pagila.
--down	Tear down the throwaway containers.

pretensor init

Interactive first-run setup wizard: connect a database, link a code repository, and register with your MCP client, in one guided flow. Infers what it can from the environment (a DSN from DATABASE_URL, POSTGRES_URL, or assembled from PGHOST/PGUSER/PGDATABASE (plus optional PGPORT, PGPASSWORD); the current directory as a candidate repo if it’s a git repo with scannable files; installed MCP clients), shows a summary, and asks a single Yes/No/Customize question. Choosing Customize walks through the same per-item questions individually. Indexes the database, optionally links and analyzes a code repository (recorded under repositories: in config.yaml), and registers pretensor with detected MCP clients, each one only with per-client confirmation or an explicit --client. Client config files are backed up with a timestamped copy before any write.

Flag	Purpose
--dsn <url>	Database URL to index; skips DSN detection.
--dialect <name>	Force the dialect (postgres, mysql, snowflake, bigquery) instead of inferring it from the DSN. Also pre-selects the dialect when building a DSN from parts.
--name <name>	Connection name (default: database name from the DSN).
--state-dir <dir>	Directory for registry.json and graph files. Default .pretensor.
--repo <path>	Code repository to link with analyze; skips repository detection.
--no-repo	Skip repository linking entirely.
--sample	Use the bundled sample database instead of your own; points you at pretensor quickstart rather than running setup itself.
--yes	Accept every default and never prompt.
--no-mcp-write	Do not write into MCP client configs, in any mode.
--client <key>	Register with this MCP client explicitly (claude-code, claude-desktop, or cursor). Repeatable.

Under --yes, or when stdin isn’t a TTY (PRETENSOR_NONINTERACTIVE=1 or non-interactive detection), init never prompts. It also never writes into an MCP client’s config on your behalf unless that client was named with --client: merely detecting Claude Desktop or Cursor installed is not consent to edit its file. Claude Code registers through claude mcp add rather than a config file. Without --client, unattended runs print the mcpServers JSON block instead, the same block pretensor serve --config-only prints.

pretensor index [dsn]

Introspect a database, build the Kuzu graph, run the intelligence pipeline. Takes a DSN argument, --source <name> (a registered connection), or --all.

Flag	Purpose
--source <name> / --all	Index a registered connection by name, or every registered connection, instead of passing a DSN. This --all iterates every source configured under sources: in config.yaml; analyze --all iterates the repositories configured under repositories:.
--dialect	Override dialect detection for the DSN.
--state-dir	State directory (registry, keystore, search index, and graphs/ subdir holding <name>.kuzu files). Default .pretensor/.
--name	Label this connection in the registry. The graph is written to <state-dir>/graphs/<name>.kuzu.
--unified	Merge into a single shared multi-database graph at <state-dir>/graphs/unified.kuzu.
--embeddings/--no-embeddings	Compute table embeddings during indexing. Defaults to on when the embeddings extra is installed.
--visibility <file> --profile <name>	Apply visibility filtering at index time. See Privacy.
--dbt-manifest <path> --dbt-sources <path>	Enrich LINEAGE edges with dbt project metadata.
--skills-target <claude|cursor|all|path>	Emit a SKILL.md agent-guidance file alongside the graph.

pretensor reindex [dsn]

Diff the live schema against the stored snapshot and patch only what changed. Cheaper than re-running index.

Flag	Purpose
--source <name> / --all	Reindex a registered connection by name, or every registered connection.
--database <name>	Target one indexed database.
--dialect	Override dialect detection.
--dry-run	Preview the diff without writing.
--recompute-intelligence	After patching the schema, re-run classify / cluster / label / join-path stages.
--embeddings/--no-embeddings	Refresh table embeddings after patching.
--state-dir	State directory. Default .pretensor/.
--skills-target --dbt-manifest --dbt-sources	Same as index.

pretensor serve

Run the MCP stdio server.

Flag	Purpose
--state-dir	State directory containing registry.json and graphs/<name>.kuzu files (default .pretensor/). --graph-dir remains as a deprecated alias.
--visibility <file> --profile <name>	Re-filter at serve time, on top of any index-time filtering.
--config-only	Don’t run; print the mcpServers JSON for your client and exit.
--print-config/--no-print-config	Also print the resolved config when starting the server.

pretensor list

Show every indexed connection plus table counts. --state-dir overrides the default.

pretensor validate <sql>

Validate a SQL statement against the indexed graph before execution. The argument is SQL text or a path to a .sql file.

Flag	Purpose
--database <name> / -d	Target one indexed connection (--db remains as a deprecated alias).
--dialect	Dialect override.
--json	Machine-readable output.

pretensor analyze [path]

Statically scan a repository for code that references your indexed tables and record those services as consumers in the graph (they surface through the consumers and impact MCP tools). Defaults to scanning the current directory. Bare .sql files are scanned too, not just SQL embedded in Python source: each one counts as a single high-confidence consumer, with table references unioned across its statements.

Flag	Purpose
--connection <name>	Required unless --all is passed. The indexed connection whose tables the scan resolves against.
--all	Analyze every repository listed under repositories: in config instead of one path. The positional path and --service are ignored when this is set: each repository uses its own path/service from config.
--service <name>	Name the consuming service (default: repository directory name). Ignored with --all.
--include <glob> --exclude <glob>	Narrow which files are scanned.
--max-file-bytes	Skip files larger than this.
--min-confidence	Drop low-confidence reference matches.
--default-schema	Schema assumed for unqualified table names.
--dry-run	Report what would be recorded without writing to the graph.
--json	Machine-readable output. With --all, emits a single JSON array of per-repository summaries instead of one object.
--state-dir	State directory. Default .pretensor/.

pretensor benchmark

Subcommand group for the 3-level benchmark harness (graph-quality metrics on stdout as JSON, human output on stderr). See pretensor benchmark --help.

pretensor sync-grants

Generate role-keyed visibility profiles from live database grants.

Flag	Purpose
--dsn <dsn>	Connection string with read access to system grants.
--name <name>	Use a registered connection instead of a DSN.
--roles <r1,r2>	Limit the profile generation to specific roles.
--output <path>	Write the resulting visibility.yml.

pretensor add | remove

Manage named connections in the registry without re-indexing (add <dsn> --name <name>, remove <name>).

pretensor export

Export the graph to a portable format. Flag set varies — see pretensor export --help.

pretensor semantic

Subcommand group for compiling metric YAML to SQL. Metric templates are not emitted by the default OSS indexing flow today; see pretensor semantic --help if you’ve authored your own.

What gets written during index

Step	Output
Schema introspection	SchemaTable + SchemaColumn nodes; explicit FK edges; snapshots
Structural lineage	LINEAGE edges from connector metadata + optional dbt enrichment
Classification	role, role_confidence, classification signals on tables
Clustering	Cluster nodes and IN_CLUSTER edges
Join paths	JoinPath nodes reachable via FK and inferred joins
Skill file	.claude/skills/pretensor-{name}/SKILL.md (or whatever --skills-target directs)

See the Schema Graph page for the full node and edge inventory.