Lone Badger Tech

Command reference

Every trek command and option (version 0.6.0).

CommandOptionsDoes
trek init[--provider sqlserver|postgresql|sqlite] [--no-agents-file]Create trek.yaml, trek.plan, folders, .gitattributes and AGENTS.md (instructions for AI assistants).
trek add <name>[-r|--requires a b] [-n|--note text] [--notx] [--irreversible] [--author name]Scaffold changes/<name>/ and append it to the plan. The author recorded in the plan is --author, else TREK_AUTHOR, else git's user.name.
trek add <name> --from-diff[--shadow-env env] [--keep-shadow] [--exclude schema.name…] [--dry-run] [--no-record] [-r …] [-n …]Generate deploy.sql and revert.sql from schema edits made in the environment's database, compared with a shadow database built from the plan; records the change as applied there.
trek tag <name>Tag the last change in the plan (use as @name).
trek plan checkValidate plan, folders, lint and variable definitions. No database.
trek plan showChanges with script hashes and chain ids; the plan head. No database.
trek status[--exit-code]Plan versus database: pending, applied, edited, orphans, certified. --exit-code returns 3 when not up to date.
trek deploy[--to change|@tag] [--dry-run] [--script file] [--ordering dependency|strict] [-y]Provision environment resources, deploy pending changes, apply changed repeatables, record a schema fingerprint. --script writes a reviewable SQL file instead.
trek revert--to x | --last n | --all | --repeatable name… [--dry-run] [-y] [--allow-variable-drift]Revert with the scripts stored at deploy time; --repeatable restores a repeatable's previous definition.
trek rebase--to x [-y] [--allow-variable-drift]Revert to x, then deploy to the head.
trek rework <change>[--as name] [-n|--note text]Add a change that supersedes a deployed one: a copy of its deploy script to edit, with a revert that restores it.
trek repair[changes…] | --all [--reason text] [--dry-run] [-y]Accept edits to deployed changes without running SQL; re-chains and re-certifies the journal.
trek bundle create[-o file] [--no-config]Write a hash-verified bundle of the project. No database.
trek bundle verify <file>Check every file in a bundle against its manifest. No database.
trek diff-schema[--against env] [--exit-code] [--script file]Schema differences: live versus the schema recorded after the last deploy, or versus another environment. --exit-code returns 3 when they differ; --script writes SQL that turns this database into the other.
trek verifyHashes versus working copy, rendered-SQL drift, verify scripts (rolled back), schema drift. Exit 1 on problems.
trek log[-n|--limit 50]Deploy, revert, fail, repeatable and resource events, newest first.
trek baseline--to x | --from flyway|dbup|ef|grate|roundhouse|sqitch|sqlproj [--journal schema.table] [--skip-checksums] [-y]Record changes as applied without running them: up to x, or as far as the old tool's journal in the database says (with repeatables it already applied, or whose live definition matches). --from sqlproj: the database was published from the SQL project.
trek import flyway <folder>[--config file] [--location dir…] [--provider sqlserver|postgresql|sqlite] [--dry-run]Convert a Flyway project into a new trek project (written to -C). No database.
trek import dbup <folder>[--file-names] [--run-always glob…] [--no-variables] [--var name=value…] [--dry-run]Convert DbUp scripts into a new trek project (written to -C). No database.
trek import ef <project folder|up.sql>[--down down.sql] [--context name] [--startup-project dir] [--provider …] [--dry-run]Convert Entity Framework Core migrations into a new trek project: runs dotnet ef in the project (which builds it), or reads scripts from dotnet ef migrations script. No database.
trek import grate <folder>[--folder key=name…] [--environment name…] [--ignore-directory-names] [--no-tokens] [--var name=value…] [--dry-run]Convert a grate or RoundhousE scripts folder into a new trek project. No database.
trek import sqitch <folder>[--engine name] [--provider …] [--dry-run]Convert a Sqitch project into a new trek project. No database.
trek import sqlproj <file.sqlproj|folder>[--dry-run]Convert an SSDT / SQL Database Project into a new SQL Server trek project: one change or repeatable per object, in dependency order. No database.
trek convert schema --out <folder>--to p [--from-provider p] [--names lower|snake|keep] [--case-sensitive] [--exclude glob…] [--dry-run]Read a SQL Server, PostgreSQL, MySQL, MariaDB or SQLite database's catalog and write a new project for the provider named by --to: tables, keys and indexes as changes; views, routines and triggers translated as repeatables; CONVERSION.md listing what to review.
trek convert data --target <folder>[--target-env env] [--from-provider p] [--tables glob…] [--truncate]Copy every table's rows into the deployed, converted project's database, then compare row counts.
trek varsEvery variable for the environment: value, source, description.
trek render <name>[-k|--kind deploy|revert|verify]Print a change or repeatable exactly as it would run.
trek ai-guidePrint the guide for AI assistants writing changes (Markdown). No database.
trek mcpRun an MCP server over stdio for AI assistants: tools that read and write this project's files. No database. See AI assistants.
trek env listEnvironments and templates.
trek env showThe selected environment, merged, secrets masked.
trek env statusEnvironment resources (Always Encrypted keys) versus the database.
trek env provision[--dry-run] [--allow-destructive] [-y]Create or rotate environment resources without deploying changes.
trek auth clearForget saved Entra sign-ins.
trek doctorConfiguration, Entra token, connection, server facts, journal, resources.

Global options

OptionMeaning
-C, --project <dir>Project folder (default: current folder)
-e, --env <name>Environment (default: TREK_ENV, then defaultEnvironment, then the only one)
--var name=valueScript variable; repeatable; overrides trek.yaml
--connection-string "..."Connect exactly here for this run
--bundle <file>Take the plan and scripts from a verified bundle instead of the project folder (and trek.yaml too, when bundled)
--claim-environmentAccept a database recorded under another environment and re-record it
--jsonMachine-readable output on stdout (warnings go to stderr)
-v, --verboseServer messages (PRINT), fingerprints, tunnel details
--no-colorNo ANSI colors; NO_COLOR and redirected output also turn them off
--version, -hVersion; help for any command

Exit codes

CodeMeaning
0Success
1Failure: a script error, a problem found by plan check or verify, a refused action, bad configuration, or a command-line usage error
3status --exit-code: not up to date; diff-schema --exit-code: schemas differ

Environment variables

VariableMeaning
TREK_ENVDefault environment
TREK_AUTHORAuthor written by trek add (default: OS user)
TREK_HOMEWhere saved sign-ins live (default ~/.trek)
NO_COLORDisable colors

Confirmation

Revert, rebase, repair, baseline and destructive provisioning ask for confirmation. In a protected environment, so does deploy, and you must type the environment name. Non-interactive runs (redirected input, --json) fail instead of hanging unless you pass --yes.

JSON output

trek status -e prod --json | jq '.certified, .databaseHead'
trek log --json -n 20