CLI Reference¶

Command-line interface for Queen migrations.

Building the CLI¶

Queen's CLI is embedded — you build it as part of your project. Create a cmd/queen/main.go:

package main

import (
    "github.com/honeynil/queen/cli"
    "myapp/migrations"
)

func main() {
    cli.Run(migrations.Register)
}

Build and run:

go build -o queen ./cmd/queen
queen version

For bootstrap commands (init, create, import, version) that don't need a database or registered migrations, you can use cli.Run(nil).

See Installation for full setup details.

Quick Start¶

queen init --driver postgres       # Initialize project
queen create add_users             # Create migration
queen up                           # Apply migrations
queen status                       # Check status

Command Categories¶

Category	Commands	Description
Core	up, down, goto, reset	Apply and rollback migrations
Info	status, log, version, diff	View migration state and history
Management	create, squash, baseline	Create and manage migrations
Diagnostics	doctor, check, validate, plan, explain	Validate and troubleshoot
Gap	detect, fill, analyze, ignore	Handle missing migrations
Utilities	init, import, tui	Setup and tools

Global Flags¶

Available on all commands:

Flag	Type	Default	Description
`--driver`	string	-	Database driver (postgres, mysql, sqlite, clickhouse)
`--dsn`	string	-	Connection string
`--table`	string	`queen_migrations`	Migration table name
`--timeout`	duration	-	Lock timeout (e.g. 30m, 1h)
`--use-config`	bool	`false`	Use .queen.yaml configuration
`--env`	string	-	Environment from config file
`--unlock-production`	bool	`false`	Unlock production environment
`--yes`	bool	`false`	Skip confirmations (CI/CD)
`--json`	bool	`false`	JSON output
`--verbose`	bool	`false`	Verbose logging

Configuration¶

Environment Variables¶

export QUEEN_DRIVER=postgres
export QUEEN_DSN="postgres://localhost/mydb"
export QUEEN_TABLE=queen_migrations

Config File¶

.queen.yaml:

naming:
  pattern: sequential_padded
  padding: 3
  enforce: true

development:
  driver: postgres
  dsn: "postgres://localhost/mydb_dev?sslmode=disable"

staging:
  driver: postgres
  dsn: "postgres://staging-host/myapp?sslmode=require"

production:
  driver: postgres
  dsn: "postgres://prod-host/myapp?sslmode=verify-full"
  require_confirmation: true
  require_explicit_unlock: true

queen up --use-config --env production --unlock-production

Priority¶

Command-line flags (highest)
Environment variables
Configuration file
Defaults (lowest)

Exit Codes¶

Code	Description
0	Success
1	General error
2	Configuration error (e.g. failed to connect to database)
3	Validation failed
4	Gaps detected
5	Pending migrations (with `--no-pending`)