Command-line reference
The binary is bluep. Every command is bluep <command> [subcommand] [arguments]; bluep help <command> and
bluep <command> --help print the same text. Exit codes: 0 success; 1 the command found differences, lint
errors or model issues; 2 usage error; 3 any other error (I/O, syntax, external command).
Model-format errors are reported as <file>:<line>:<col>: <message>, relative to the model directory.
Repository-local reviews are managed with bluep review and can be checked as a CI gate.
The sections below are generated from the help texts compiled into the binary by the test
cli_doc_is_current and are rewritten with BLUEP_UPDATE_GOLDEN=1 cargo test -p bluep-cli.
Overview
bluep 0.2.0 — data modeling tool: text models, DDL, migrations, lint, docs
Usage:
bluep <command> [arguments]
bluep help <command>
Commands:
init create a new model directory
fmt rewrite a model directory in canonical form
check parse and validate a model directory
import build a model from DDL, a live database, JSON or DBML
generate write DDL scripts or HTML documentation
diff compare a model with another model or a live database
migrate write an ALTER migration script from a comparison
pull pull schema changes from a database, DDL script or model into the model
lint check a model against naming standards and rules
serve run the local web UI
history show model-level changes between two git revisions
review create and check repository-local model reviews
merge three-way merge of three model directories
merge-file git merge driver for a single .bluep file
export write the model as JSON
report render a report from a built-in or custom template
lineage trace declared source-to-target mappings
drift detect database drift
help show help for a command
Options:
--version print the version and exit
--help print this text and exit
Exit codes:
0 success 1 differences, lint errors or model issues 2 usage error 3 other error
bluep init
bluep init — create a new model directory
Usage:
bluep init <dir> [--name <name>]
bluep init <dir> --template <template-dir> [--name <name>]
Options:
--name <name> model name
--template <template-dir> copy a validated local template
bluep fmt
bluep fmt — rewrite a model directory in canonical form
Usage:
bluep fmt <dir> [--check]
Options:
--check rewrite nothing; print "would rewrite <file>" for each file not in canonical form and exit 1
bluep check
bluep check — parse and validate a model directory
Usage:
bluep check <dir> [--json]
Options:
--json print the result as a JSON object on stdout instead of text
bluep import
bluep import — build a model from DDL, a live database, JSON, DBML or application schemas
Usage:
bluep import ddl <file> --dialect <id> --out <dir> [--name <name>] [--report <path>] [--infer-relationships] [--many-to-many] [--force]
bluep import mongodb <file> --out <dir> [--name <name>]
bluep import db --dialect <id> --database <name> [connection options] --out <dir> [--report <path>] [--force]
bluep import json <file> --out <dir>
bluep import dbml <file> --out <dir>
bluep import json-schema|avro <file> --out <dir> [--name <name>] [--root <name>] [--report <file>] [--force]
Live-import dialects: postgresql, sqlite, mysql, sqlserver, oracle, snowflake, bigquery, redshift, databricks, db2, teradata, mongodb
Options:
--dialect <id> dialect of the DDL script or the database
--out <dir> directory that receives model.bluep (created if missing)
--name <name> model name
--root <name> override the imported root record name
--report <path> write a structured reverse-fidelity JSON report
--infer-relationships infer conservative missing relationships
--many-to-many recognize pure junction tables as associations
--force overwrite an existing model.bluep in <dir>
bluep import csv <dir> --kind <kind> --file <csv> [--plan <file>]
bluep import csv <dir> --apply <plan.json> --yes [--accept <row,row,...>]
Database options (import db):
--database <name> database name; for sqlite the path of the database file
--password-env <VAR> read the password from environment variable VAR
--timeout <seconds> time limit per catalog query (default 60)
Connection options (live databases):
--host <host> server host (postgresql, mysql, sqlserver, oracle, teradata)
--port <port> server port
--user <user> user name
--password <p> database password (or BLUEP_DB_PASSWORD)
--schema <name> schema to read, repeatable (postgresql and the cloud dialects; default: public)
--option <key=value> dialect connection option, repeatable: snowflake connection=<name>;
bigquery project=<id>, region=<r>; databricks catalog=<name>
bluep import mongodb
bluep import mongodb — build a model from a validator bundle
Usage:
bluep import mongodb <file> --out <dir> [--name <name>]
bluep import ddl
bluep import ddl — build a model from a DDL script
Usage:
bluep import ddl <file> --dialect <id> --out <dir> [--name <name>] [--root <name>] [--report <path>] [--infer-relationships] [--many-to-many] [--force]
Options:
--dialect <id> dialect of the DDL script
--out <dir> directory that receives model.bluep (created if missing)
--name <name> model name (default: imported)
--root <name> root record name for application-schema imports
--report <path> write a structured reverse-fidelity JSON report
--infer-relationships infer conservative missing relationships
--many-to-many recognize pure junction tables as associations
--force overwrite an existing model.bluep in <dir>
bluep import db
bluep import db — build a model from a live database using its command-line client
Usage:
bluep import db --dialect <id> --database <name> [connection options] --out <dir> [--report <path>] [--force]
Live-import dialects: postgresql, sqlite, mysql, sqlserver, oracle, snowflake, bigquery, redshift, databricks, db2, teradata
Options:
--dialect <id> dialect of the DDL script or the database
--out <dir> directory that receives model.bluep (created if missing)
--name <name> model name (default: imported for import ddl; for import db the database
name, or the file stem for sqlite)
--report <path> write a structured reverse-fidelity JSON report
--force overwrite an existing model.bluep in <dir>
Database options (import db):
--database <name> database name; for sqlite the path of the database file
--password-env <VAR> read the password from environment variable VAR
--timeout <seconds> time limit per catalog query (default 60)
Connection options (live databases):
--host <host> server host (postgresql, mysql, sqlserver, oracle, teradata)
--port <port> server port
--user <user> user name
--password <p> database password (or BLUEP_DB_PASSWORD)
--schema <name> schema to read, repeatable (postgresql and the cloud dialects; default: public)
--option <key=value> dialect connection option, repeatable: snowflake connection=<name>;
bigquery project=<id>, region=<r>; databricks catalog=<name>
Inference options:
--infer-relationships infer conservative missing relationships
--many-to-many recognize pure junction tables as associations
Live-import dialects: mongodb
bluep import json
bluep import json — build a model from a JSON interchange file
Usage:
bluep import json <file> --out <dir>
bluep import dbml
bluep import dbml — build a model from a DBML file
Usage:
bluep import dbml <file> --out <dir>
bluep import csv
bluep import csv — plan or apply a bulk CSV snapshot
Usage:
bluep import csv <dir> --kind entities|attributes|columns|relationships|properties --file <csv> [--plan <file>]
bluep import csv <dir> --apply <plan.json> --yes [--accept <row,row,...>]
bluep generate
bluep generate — write DDL scripts or HTML documentation
Usage:
bluep generate ddl <dir> (--target <name> | --dialect <id>) [--out <file>] [--template-dir <dir>]
bluep generate docs <dir> --out <outdir>
bluep generate diagram <dir> [--area <name>] [--diagram <name>] --format svg|pdf|png --out <file> [--scale 1|2]
Dialects:
postgresql sqlite mysql sqlserver oracle snowflake bigquery redshift databricks db2 teradata mongodb
bluep generate ddl
bluep generate ddl — write a CREATE script for one target or dialect
Usage:
bluep generate ddl <dir> (--target <name> | --dialect <id>) [--out <file>] [--template-dir <dir>]
Dialects:
postgresql sqlite mysql sqlserver oracle snowflake bigquery redshift databricks db2 teradata mongodb
bluep generate docs
bluep generate docs — write a static HTML data dictionary with SVG diagrams
Usage:
bluep generate docs <dir> --out <outdir>
bluep generate diagram
bluep generate diagram — write a deterministic diagram
Usage:
bluep generate diagram <dir> [--area <name>] [--diagram <name>] --format svg|pdf|png --out <file> [--scale 1|2]
Options:
--area <name> export one subject area
--diagram <name> named presentation diagram (default Default)
--format svg|pdf|png output format (required)
--out <file> output file (required)
--scale 1|2 PNG raster scale (default 1)
bluep diff
bluep diff — compare a model target with another model directory or a live database
Usage:
bluep diff <dir> --target <name> --against-dir <dir2> [options]
bluep diff <dir> --target <name> --against-db <database> [connection options] [options]
Live-import dialects: postgresql, sqlite, mysql, sqlserver, oracle, snowflake, bigquery, redshift, databricks, db2, teradata
Options:
--json print the change set as JSON
--accept-renames treat rename candidates as renames
--ignore-comments ignore comment differences
--ignore-mapping ignore changes to the entity, attribute or relationship an object maps to
--ignore-properties ignore property and classification differences
Connection options (live databases):
--host <host> server host (postgresql, mysql, sqlserver, oracle, teradata)
--port <port> server port
--user <user> user name
--password <p> database password (or BLUEP_DB_PASSWORD)
--schema <name> schema to read, repeatable (postgresql and the cloud dialects; default: public)
--option <key=value> dialect connection option, repeatable: snowflake connection=<name>;
bigquery project=<id>, region=<r>; databricks catalog=<name>
Live-import dialects: mongodb
bluep migrate
bluep migrate — write an ALTER migration script from a comparison
Usage:
bluep migrate <dir> --target <name> (--against-dir <dir2> | --against-db <database> [connection options])
[options]
Live-import dialects: postgresql, sqlite, mysql, sqlserver, oracle, snowflake, bigquery, redshift, databricks, db2, teradata
Options:
--dialect <id> write the script for this dialect (default: the target's)
--out <file> write the script to a file instead of stdout
--allow-destructive include drops and type changes (default: skipped, with a count on stderr)
--accept-renames treat rename candidates as renames
--ignore-comments ignore comment differences
--ignore-properties ignore property and classification differences
--no-transaction do not wrap the script in a transaction
Connection options (live databases):
--host <host> server host (postgresql, mysql, sqlserver, oracle, teradata)
--port <port> server port
--user <user> user name
--password <p> database password (or BLUEP_DB_PASSWORD)
--schema <name> schema to read, repeatable (postgresql and the cloud dialects; default: public)
--option <key=value> dialect connection option, repeatable: snowflake connection=<name>;
bigquery project=<id>, region=<r>; databricks catalog=<name>
Live-import dialects: mongodb
bluep deploy
bluep deploy — safely apply a migration to a live database
Usage:
bluep deploy <dir> --target <name> --database <database> [connection options]
[--dry-run] [--allow-destructive] --rollback-out <file> [--applied-by <text>]
bluep deploy <dir> --target <name> --database <database> [connection options] --status
Options:
--dry-run print the migration and write the rollback script; change nothing
--allow-destructive also apply drops and type changes (otherwise the deploy is blocked)
--rollback-out <file> write the rollback script here before anything changes (required)
--applied-by <text> who deployed, recorded in the history (default: --user, then BLUEP_DEPLOY_ACTOR)
--status show the deployments recorded in the database
Connection options (live databases):
--host <host> server host (postgresql, mysql, sqlserver, oracle, teradata)
--port <port> server port
--user <user> user name
--password <p> database password (or BLUEP_DB_PASSWORD)
--schema <name> schema to read, repeatable (postgresql and the cloud dialects; default: public)
--option <key=value> dialect connection option, repeatable: snowflake connection=<name>;
bigquery project=<id>, region=<r>; databricks catalog=<name>
bluep drift
bluep drift — detect database drift
Usage:
bluep drift <dir> --target <name> (--database <db> [connection options] | --ddl <file> --dialect <id>)
[--since-deploy] [--ignore <file>] [--format text|json|html] [--out <file>] [--fail-on drift|any|none]
Options:
--since-deploy separate live changes from model changes made since the last deploy (needs --database)
--ignore <file> drift ignore rules (default: <dir>/.bluep-drift-ignore when it exists)
--format <f> text, json or html (default text; html needs --out)
--out <file> write the report to a file instead of stdout
--fail-on <when> drift (default): exit 1 on database drift or conflicts; any: exit 1 on any
difference; none: exit 0 after a successful inspection
--accept-renames treat rename candidates as renames
--ignore-comments ignore comment differences
--ignore-properties ignore property and classification differences
Connection options (live databases):
--host <host> server host (postgresql, mysql, sqlserver, oracle, teradata)
--port <port> server port
--user <user> user name
--password <p> database password (or BLUEP_DB_PASSWORD)
--schema <name> schema to read, repeatable (postgresql and the cloud dialects; default: public)
--option <key=value> dialect connection option, repeatable: snowflake connection=<name>;
bigquery project=<id>, region=<r>; databricks catalog=<name>
bluep pull
bluep pull <dir> --target <name> <source> [options]
Compare the model's target with a source and bring the source's schema into the
model. A plan lists every difference; applying writes the accepted changes into
the model files with minimal edits and propagates them to the logical layer
(entities, attributes, keys, relationships).
Sources (exactly one):
--from-dir <dir2> [--from-target <name>] another model directory (default: same target name)
--from-ddl <file> [--dialect <id>] a DDL script (default dialect: the target's)
--from-db --database <name> [--dialect <id>] [--host <h>] [--port <p>] [--user <u>]
[--schema <s>]... [--option k=v]...
a live database through its command-line client
Modes:
(none) print the plan with [x]/[ ] markers; exit 1 when there are changes
--plan <file> write the plan as JSON for review and editing
--apply <file> apply the items marked "apply": true in a plan file
--yes plan and apply in one step
Options:
--allow-destructive also apply drops and type changes (default: listed but not applied)
--no-logical change only the physical target, not entities and attributes
--accept-renames treat rename candidates as renames
--ignore-comments ignore comment differences
--infer-relationships plan conservative missing relationships as inferred, unchecked items
--accept-inferred-relationships accept non-destructive inferred relationship items
--password <p> database password for --from-db (or BLUEP_DB_PASSWORD)
Live-import dialects: postgresql, sqlite, mysql, sqlserver, oracle, snowflake, bigquery, redshift, databricks, db2, teradata
Exit codes: 0 nothing to do or applied, 1 plan has changes (default mode), 2 usage error, 3 other error
Live-import dialects: mongodb
bluep lint
bluep lint — check a model against naming standards and lint rules
Usage:
bluep lint <dir> [--json] [--level warn|error]
bluep serve
bluep serve — run the local web UI
Usage:
bluep serve <dir> [--port <port>] [--host <host>] [--team [--users <file>] [--audit <file>]] [--allow-remote-http]
Team mode is HTTP-only and refuses non-loopback hosts unless --allow-remote-http is set.
bluep team
bluep team — manage local team-server accounts
Usage:
bluep team user add --users <file> <username> --display-name <name> --email <email> --role viewer|editor|admin --password-stdin
bluep team user passwd --users <file> <username> --password-stdin
bluep team user enable|disable --users <file> <username>
bluep team user list --users <file>
bluep history
bluep history — show model-level changes between two git revisions
Usage:
bluep history <dir> --from <rev> --to <rev> [--json]
bluep review
bluep review — create and check repository-local model reviews
Usage:
bluep review create <dir> (--from <rev> --to <rev> | --branch <rev> --base <rev>) [--id <id>]
bluep review list [<dir>] [--state <state>] [--json]
bluep review show <dir> <id> [--json]
bluep review comment <dir> <id> (--anchor <anchor> | --thread <thread>) --body <text>
bluep review resolve <dir> <id> <thread>
bluep review approve|request-changes|close <dir> <id>
bluep review check <rev> [--dir <dir>]
bluep merge
bluep merge <base_dir> <ours_dir> <theirs_dir> --out <dir> [--prefer ours|theirs] [--json]
Three-way, model-aware merge of three model directories (the common ancestor, your version, the other
version). The merged model is written to <dir> in canonical form even when there are conflicts; conflicts
are printed as 'CONFLICT <path>: base .. | ours .. | theirs ..' and resolved in favour of ours (or theirs
with --prefer theirs). --json prints the conflicts as a JSON array instead.
Exit codes: 0 clean merge, 1 conflicts, 2 usage error, 3 other error.
bluep merge-file
bluep merge-file <base> <ours> <theirs> [--prefer ours|theirs]
Git merge driver for one .bluep file. Merges the three versions at the model level, writes the canonical
result over <ours> and prints conflicts to stderr. Configure with:
git config merge.bluep.name "bluep model merge"
git config merge.bluep.driver "bluep merge-file %O %A %B"
and '*.bluep merge=bluep' in .gitattributes.
Exit codes: 0 clean merge, 1 conflicts, 2 usage error, 3 other error.
bluep export
bluep export — write the model as JSON, CSV or application schemas
Usage:
bluep export json <dir> [--resolved] [--out <file>]
bluep export csv <dir> --kind entities|attributes|columns|relationships|properties
bluep export json-schema|avro|protobuf|typescript <dir> [--root <entity>] [--nest references|identifying] [--out <file>] [--report <file>]
bluep export json
bluep export json — write the model in the JSON interchange format
Usage:
bluep export json <dir> [--resolved] [--out <file>]
--resolved inline effective library exports and add resolved_sources provenance
bluep export csv
bluep export csv — write a deterministic bulk-editing snapshot
Usage:
bluep export csv <dir> --kind entities|attributes|columns|relationships|properties
bluep report
bluep report — render a report from a built-in or custom template
Usage:
bluep report <dir> --template <name> [--format html|csv|md|txt] [--out <file>] [--var k=v]...
bluep report <dir> --template-file <path> [--format html|csv|md|txt] [--out <file>] [--var k=v]...
bluep report --list
Options:
--template <name> built-in template (see --list)
--template-file <path> custom template; the output format defaults from its extension
--format <f> output format: html, csv, md or txt (default: from the template name, else txt)
--out <file> write to a file instead of stdout
--var <k>=<v> define a template variable, available as vars.<k>
--list print the built-in templates and exit
The template context has model (the model as JSON), meta (name, version, description),
lint (the lint findings) and vars. See docs/reports.md for the template language.
Exit codes: 0 success 2 usage error 3 template or model error
bluep lineage
bluep lineage <dir> <object> [--upstream|--downstream|--both]
[--level table|column] [--max-depth <n>] [--json]
bluep help
bluep help — show help for a command
Usage:
bluep help [<command> [<subcommand>]]