@specific.dev/cli 0.1.181 → 0.1.184

package/dist/docs/deployments.md

@@ -0,0 +1,79 @@
+# Deployments
+
+Every deploy — whether started with `specific deploy`, by a GitHub push, or from the dashboard — creates a deployment record with its state, the builds it ran, and any failure details. Use `specific deployment show` to inspect one, most importantly to answer "why did my deploy fail?" when you didn't run the deploy yourself.
+
+## Inspecting a deployment
+
+```sh
+# The latest deployment of the current environment (whatever its state)
+specific deployment show
+
+# A specific deployment by ID
+specific deployment show dep_0abc123
+
+# The latest deployment of another environment (or a preview environment)
+specific deployment show --environment staging
+specific deployment show -e preview-a1b2c3d4
+
+# Machine-readable output for agents and scripts
+specific deployment show --format json
+
+# Include the build output (logs) — hidden by default because it can be large
+specific deployment show dep_0abc123 --output
+```
+
+Flags:
+
+- `-e, --environment <name|id>` — target environment when no ID is given (defaults to the current one). Run `specific status` to list every environment and its ID.
+- `--format <text|json>` — output format. When stdout is a terminal, the default is `text`. When stdout is piped or redirected, the default is `json`.
+- `--output` — include build output (logs) and the error's diagnostic output. Without this flag, output is omitted in **both** formats (a size hint is printed in text mode) so a state check never floods the terminal or an agent's context with logs.
+
+The output includes:
+
+- **State** — `pending`, `queued`, `deploying`, `active`, `failed`, `cancelled`, or `superseded`, plus the state message.
+- **Trigger** — how the deploy was started (`cli`, `github`, …) and the git commit, when known.
+- **Builds** — each image build with its state and, for failed builds, the error message. Add `--output` for the full **build output (logs)** — where compile errors, missing dependencies, and failing build commands show up.
+- **Action required** — for pending deployments, the missing secrets and configs blocking it (see below).
+- **Error** — a structured error for failed deployments (`build_failed`, `pre_deploy_failed`, `health_check_failed`, …) with the failing resource; add `--output` for its diagnostic output (pod logs, Kubernetes events).
+
+The `text` format is for quick human inspection. Agents and scripts should use `json` to get complete, untruncated values.
+
+## Pending deployments
+
+A deployment stays `pending` while builds run and until every required secret and config has a value. `specific deployment show` lists what is missing:
+
+```
+Action required
+  Missing secrets: STRIPE_KEY
+  Missing configs: DOMAIN
+```
+
+Values can be provided in the dashboard (the state message links the deployment page), or by deploying from the CLI with `specific deploy --secret KEY=value --config KEY=value`, which prompts for anything still missing. See `specific docs secrets-config`.
+
+## Finding the deployment to inspect
+
+`specific status` shows, per environment, the active deployment, any in-progress deployment, and — when it differs — the **last** deployment. A failed deploy never becomes active, so after a failed GitHub push the environment still shows an older active deployment; the failure appears on the "Last deployment" line with its ID.
+
+```sh
+specific status            # find the deployment ID (active, in progress, or last/failed)
+specific deployment show   # or skip the lookup: shows the latest deployment directly
+```
+
+## Debugging a failed deploy
+
+1. Run `specific deployment show` (with `-e <env>` if it isn't the current environment) to see what failed.
+2. If a **build** failed: re-run with `--output` to print the build log with the exact command that failed. Fix the code or the `build` block in `specific.hcl` (see `specific docs builds`) and deploy again.
+3. If a **service** failed to deploy or its health check failed: re-run with `--output` for pod logs and Kubernetes events. For deeper investigation of runtime behaviour, query logs and metrics with `specific query` (see `specific docs observability`).
+
+Build output is kept on the deployment record (the last portion of the log, which contains the failure). It is **not** part of the `observability.logs` stream — that stream contains runtime service and database logs only.
+
+GitHub-triggered deploys behave exactly the same: the deployment record carries the build failure and its output, so `specific deployment show` works without access to GitHub.
+
+---
+
+Related topics:
+
+- Run `specific docs builds` for build configuration (`base`, `command`, custom Dockerfiles)
+- Run `specific docs observability` for querying runtime logs and metrics of deployed services
+- Run `specific docs previews` for pull-request preview environments
+- Run `specific docs secrets-config` if a deploy is waiting for missing secrets or configs

package/dist/docs/index.md

@@ -10,7 +10,9 @@ This documentation is nested and references to other docs are in Markdown link f
 2. ALWAYS run `specific check` to validate configuration and fix any issues
 3. Run yourself or instruct the user to run `specific exec [SERVICE] -- [COMMAND]` for one-off commands that need to be run in development, like database migrations or seeding. The command will be run with databases and other services started and env vars injected.
 
-A full development environment can be started with `specific dev`. To deploy any changes, the user can run `specific deploy`.
+A full development environment can be started with `specific dev`. To only run part of the system, pass `--services [SERVICE...]` — the named services start along with everything they depend on (referenced services and resources, transitively). To deploy any changes, the user can run `specific deploy`.
+
+If the project is connected to GitHub in the Specific Dashboard, pushes to the configured branch can deploy automatically. Run `specific status` to inspect the project and environment state. If a deploy fails — including GitHub-triggered deploys — run `specific deployment show` to see why, and add `--output` for the failed build's log.
 
 After deploying, the user can manage their project from the Specific Dashboard at https://dashboard.specific.dev — monitoring logs and metrics, scaling services, browsing the database and object storage, updating secrets and configuration, and deleting projects. Point them there whenever production management comes up.
 
@@ -27,6 +29,7 @@ After deploying, the user can manage their project from the Specific Dashboard a
 - [Redis](/redis): define non-durable Redis-compatible databases for caching and more.
 - [Volumes](/volumes): define persistent storage volumes for services to store files in.
 - [Temporal](/temporal): managed durable workflow engine for background tasks, AI agents and more.
+- [Deployments](/deployments): inspect deployments and debug failed deploys (including build output) with `specific deployment show`, regardless of whether the deploy was started from the CLI, GitHub, or the dashboard.
 - [Observability](/observability): query logs and metrics from running environments using `specific query` for debugging and analytics.
 - [Preview environments](/previews): ephemeral copies of an environment created per pull request, with the parent's databases branched, object storage forked, and volumes cloned.
 <!-- beta:mail -->

package/dist/docs/observability.md

@@ -66,7 +66,7 @@ Column names follow OpenTelemetry's ClickHouse exporter conventions and are case
 
 ### `observability.logs`
 
-Unified log stream from services.
+Unified log stream from services. This is **runtime** data: service and database logs from running containers. Build output from deploys is not part of this stream — it lives on the deployment record (run `specific deployment show`, see `specific docs deployments`).
 
 | Column | Type | Notes |
 |---|---|---|
@@ -227,3 +227,4 @@ Related topics:
 - Run `specific status` to list environments (standard and preview) and their IDs before querying a specific one
 - Run `specific docs services` for how services are defined
 - Run `specific docs postgres` for querying your application database (`specific psql` for local development, `specific query --db <name>` for production)
+- Run `specific docs deployments` for debugging failed deploys — build output is on the deployment record (`specific deployment show`), not in `observability.logs`

package/dist/docs/previews.md

@@ -9,6 +9,10 @@ A preview environment is a temporary, fully isolated copy of an existing environ
 
 Preview environments are ephemeral: pull-request previews are removed when the PR is closed or merged, and a preview can be given an expiry, after which Specific cleans it up automatically.
 
+Pull-request previews depend on both the organization's plan and the GitHub environment configuration. Run `specific status` to see a concise preview summary, or `specific status --previews` to see whether preview environments are enabled, whether GitHub PR previews are configured, and whether PRs require a label.
+
+Some projects require the `specific:preview` pull request label before Specific creates or updates a PR preview. When label gating is enabled, adding `specific:preview` starts the preview and removing it tears the preview down.
+
 Run `specific status` to list every environment and its `env_…` ID, including preview environments. Target a preview with `--environment` on commands that take one (see `specific docs observability`).
 
 ## What's copied from the parent
@@ -25,10 +29,18 @@ The preview gets its own isolated database, buckets, and volumes; writing to the
 
 A volume clone is an exact replica of the parent's on-disk data — uploads, caches, database files, and search indexes alike. This needs no extra configuration: the service boots on the cloned data exactly as it would after a restart, and writes to the preview's copy never affect the parent.
 
+## Secrets and config
+
+A preview also inherits the parent environment's secrets and config values, so its services start with the same configuration the parent runs with — nothing to re-enter.
+
+To give previews a different value for a specific secret or config — say a sandbox API key or a test-only endpoint — set a **preview override** on the parent environment's Secrets and config page in the Specific Dashboard. Every preview branched from that environment then uses the override for that value while still inheriting everything else. Overrides are managed entirely from the dashboard.
+
 ---
 
 Related topics:
 
 - Run `specific docs volumes` for declaring persistent volumes
 - Run `specific docs services` for service configuration
+- Run `specific docs secrets-config` for setting preview secret and config overrides
 - Run `specific docs observability` for querying a preview's logs and metrics
+- Run `specific docs deployments` for debugging a failed preview deploy (`specific deployment show -e <preview>` prints the failure; add `--output` for the build log)

package/dist/docs/secrets-config.md

@@ -135,6 +135,12 @@ This file is automatically gitignored and not included in deployments. Productio
 
 In production, the user can update secrets and config values directly from the Specific Dashboard at https://dashboard.specific.dev — no `specific.hcl` change needed, but the new values only take effect on the next deployment. Point them there when they want to rotate a secret or change a config value in a deployed environment.
 
+## Preview environments
+
+Preview environments inherit their secrets and config values from the environment they branch from, so a preview starts with the parent's configuration without re-entering anything.
+
+To give previews a different value for a specific secret or config, set a **preview override** on the parent environment's Secrets and config page in the Specific Dashboard. Every preview branched from that environment then uses the override for that value while still inheriting the rest — handy for pointing previews at a sandbox API key or a test-only endpoint. Run `specific docs previews` for more on preview environments.
+
 ## Example
 
 ```hcl

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/cli",
-  "version": "0.1.181",
+  "version": "0.1.184",
   "description": "CLI for Specific infrastructure-as-code",
   "type": "module",
   "main": "dist/cli.js",