> ## Documentation Index
> Fetch the complete documentation index at: https://docs.specific.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

```bash theme={null}
specific init
```

| Option              | Description                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------------- |
| `--agent <name...>` | Agents to configure: `cursor`, `claude`, `codex`, `other`. Auto-detected from existing config files if omitted. |

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
specific dev
```

| Option            | Description                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| `-k, --key <key>` | Run an isolated dev environment with separate data and ports. Auto-detected from git worktrees.  |
| `--tunnel`        | Expose public services via `*.tunnel.spcf.app` URLs so others (or remote agents) can reach them. |

```bash theme={null}
# 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.

```bash theme={null}
specific exec <service> -- <command>
```

| Option            | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| `-k, --key <key>` | Dev environment namespace. Auto-detected from git worktrees.                 |
| `--cwd <path>`    | Override the working directory (defaults to `service.root` or `build.root`). |

```bash theme={null}
# 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.

```bash theme={null}
specific psql [database]
```

| Option            | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| `-k, --key <key>` | Dev environment namespace. Auto-detected from git worktrees. |

```bash theme={null}
# 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`](#specific-query) instead.

### specific reshape

Manage [Reshape](/guides/reshape) zero-downtime migrations manually. During `specific dev`, migrations are managed automatically; these commands are for manual control.

```bash theme={null}
specific reshape <check|start|complete|status|abort> [database]
```

| Option            | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| `-k, --key <key>` | Dev environment namespace. Auto-detected from git worktrees. |

```bash theme={null}
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.

```bash theme={null}
specific clean
```

| Option            | Description                                             |
| ----------------- | ------------------------------------------------------- |
| `-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`.

```bash theme={null}
specific deploy
```

| Option                         | Description                                                     |
| ------------------------------ | --------------------------------------------------------------- |
| `--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).                                     |
| `--preview`                    | Deploy to an ephemeral [preview environment](/guides/previews). |

```bash theme={null}
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.

```bash theme={null}
specific status
```

### specific query

Run a SQL query against your environment's [observability data](/guides/observability) (ClickHouse), or against a production Postgres database with `--db` (read-only).

```bash theme={null}
specific query "SELECT count() FROM observability.logs"
```

| Option                               | Description                                                                                    |
| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `-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.                               |

```bash theme={null}
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](https://dashboard.specific.dev).

```bash theme={null}
specific domain add <service> <domain>
```

| Option                         | Description                                       |
| ------------------------------ | ------------------------------------------------- |
| `-e, --environment <name\|id>` | Target environment (defaults to the current one). |

```bash theme={null}
specific domain add web api.example.com
specific domain add web example.com --environment staging
```

### specific project

Manage projects.

```bash theme={null}
specific project new <name>
specific project list
```

| Option       | Description                                                                   |
| ------------ | ----------------------------------------------------------------------------- |
| `--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.

```bash theme={null}
specific login
```

| Option                 | Description                                                               |
| ---------------------- | ------------------------------------------------------------------------- |
| `--device-code <code>` | Complete login using a device code from a previous non-interactive login. |

### specific logout

Log out of Specific.

```bash theme={null}
specific logout
```

### specific update

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

```bash theme={null}
specific update
```

### specific beta

Manage beta feature flags interactively.

```bash theme={null}
specific beta
```