Skip to main content
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
OptionDescription
--agent <name...>Agents to configure: cursor, claude, codex, other. Auto-detected from existing config files if omitted.
# 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
OptionDescription
-k, --key <key>Run an isolated dev environment with separate data and ports. Auto-detected from git worktrees.
--tunnelExpose public services via *.tunnel.spcf.app URLs so others (or remote agents) can reach them.
# Start an isolated environment for a feature branch
specific dev --key feature-auth

# Expose services publicly via tunnel
specific dev --tunnel

​
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>
OptionDescription
-k, --key <key>Dev environment namespace. Auto-detected from git worktrees.
--cwd <path>Override the working directory (defaults to service.root or build.root).
# 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]
OptionDescription
-k, --key <key>Dev environment namespace. Auto-detected from git worktrees.
# 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]
OptionDescription
-k, --key <key>Dev environment namespace. Auto-detected from git worktrees.
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
OptionDescription
-k, --key <key>Remove data only for the specified dev environment key.

​
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
OptionDescription
--project <id>Project ID to deploy to (overrides the saved project).
-e, --environment <name|id>Target environment. Auto-selected if only one exists.
--secret <key=value...>Secret values (repeatable).
--config <key=value...>Config values (repeatable).
--previewDeploy to an ephemeral preview environment.
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. 
specific status

​
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"
OptionDescription
-e, --environment <name|id>Target environment (defaults to the current one).
--db <name>Query a Postgres database by name with Postgres SQL (read-only) instead of observability data.
--format <table|json|jsonl|csv>Output format. Defaults to table on a TTY, jsonl when piped.
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>
OptionDescription
-e, --environment <name|id>Target environment (defaults to the current one).
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
OptionDescription
--org <id>Organization ID for new (required if you belong to multiple organizations).

​
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
OptionDescription
--device-code <code>Complete login using a device code from a previous non-interactive 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