CLI reference

Every command in the Specific CLI, grouped by workflow.

The specific CLI is the primary interface to Specific, for humans and coding agents alike. Run specific --help or specific <command> --help for built-in help.

Setup

specific init

Prepare a project for use with a coding agent. Writes Specific usage instructions into your agent’s configuration file (CLAUDE.md for Claude Code, AGENTS.md for Codex, .cursor/rules/specific.mdc for Cursor) and adds .specific and specific.local to .gitignore.

specific init

# Configure for Claude Code and Cursor
specific init --agent claude cursor

specific docs

Fetch LLM-optimized documentation bundled with the CLI. Without a topic, prints the documentation index. Topics are nested paths.

specific docs
specific docs services
specific docs postgres/reshape

specific check

Validate the specific.hcl configuration file. Lists all builds, services, databases, storage, redis, and configs defined in the file, and reports errors for invalid configurations, including Reshape migration validation.

specific check

Exits with code 1 if there are any errors. Run it after every change to specific.hcl or your migration files.

Local development

specific dev

Start the local development environment. Reads specific.hcl and starts all resources and services on local ports, printing their URLs. The local dashboard is usually at http://localhost:3000, with services on the ports next to it.

specific dev

# Start an isolated environment for a feature branch
specific dev --key feature-auth

# Expose services publicly via tunnel
specific dev --tunnel

# Only start the api and worker services (and their dependencies)
specific dev --services api worker

specific exec

Run a one-off command with a service’s environment variables and its dependencies started. If specific dev is already running, exec reuses the existing resources. Otherwise, it starts the required resources temporarily and stops them when the command finishes. This is the primary way to run database migrations, seed scripts, and other setup commands.

specific exec <service> -- <command>

# Run database migrations
specific exec api -- npm run db:migrate

# Run a cron's own command
specific exec my-cron

# Run from the repository root instead of the service root
specific exec --cwd . api -- npx expo start

The -- separator distinguishes the service arguments from the command to execute. Running specific exec <cron> without a command runs the cron’s configured command.

specific psql

Connect to a local Postgres database with an interactive psql session. If the database is not running, it is started automatically. When only one database is defined in specific.hcl, the database name is optional.

specific psql [database]

# Run a single query
specific psql main -- -c "SELECT * FROM users LIMIT 5"

# List all tables
specific psql main -- -c "\dt"

Extra arguments after -- are passed directly to psql. For production databases, use specific query --db instead.

specific reshape

Manage Reshape zero-downtime migrations manually. During specific dev, migrations are managed automatically; these commands are for manual control.

specific reshape <check|start|complete|status|abort> [database]

specific reshape status
specific reshape complete mydb

check validates migration file syntax and works without a running database; the other actions need one (started automatically if specific dev isn’t running).

specific clean

Remove local development data. Deletes the resource data stored in .specific/keys/, giving you a fresh start with empty databases and storage. Cannot be run while specific dev is active.

specific clean

Deploy and manage

specific deploy

Deploy the project to Specific Cloud. On first deploy, prompts you to log in and create or select a project; afterwards the project is remembered in .specific/project.json.

specific deploy

specific deploy --environment staging
specific deploy --preview
specific deploy --secret db_url=postgres://... --config domain=app.com

specific status

Show the current project, its environments (including preview environments and their env_... IDs), and deployment status. When the most recent deployment failed, it is listed separately from the active one with a pointer to specific deployment show.

specific status

specific deployment

Inspect deployments. show prints a deployment’s state, how it was triggered (CLI, GitHub, dashboard), its builds, any missing secrets/configs blocking a pending deployment, and — for failures — the structured error. Works for every deploy regardless of how it was started, so it’s the way to debug a failed GitHub push without digging through GitHub.

specific deployment show                 # latest deployment of the current environment
specific deployment show dep_0abc123     # a specific deployment by ID

specific deployment show --environment staging
specific deployment show --format json
specific deployment show dep_0abc123 --output

specific query

Run a SQL query against your environment’s observability data (ClickHouse), or against a production Postgres database with --db (read-only).

specific query "SELECT count() FROM observability.logs"

specific query --environment staging "SELECT * FROM observability.logs LIMIT 5"
specific query --db main "SELECT * FROM users LIMIT 5"

# Read the query from stdin
cat queries/p99.sql | specific query

specific domain

Manage custom domains for deployed services. add registers a domain and prints the DNS records you need to create. Removing a domain is done in the dashboard.

specific domain add <service> <domain>

specific domain add web api.example.com
specific domain add web example.com --environment staging

specific project

Manage projects.

specific project new <name>
specific project list

Account

specific login

Log in to Specific. Opens a browser for authentication; in non-interactive environments it prints a device-authorization link and code instead.

specific login

specific logout

Log out of Specific.

specific logout

specific update

Update the Specific CLI to the latest version. The CLI also auto-updates in the background.

specific update

specific beta

Manage beta feature flags interactively.

specific beta