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

# fjall ci

> Set up CI deploys, verify pipeline readiness, manage CI deploy tokens, and run deploys non-interactively from any CI system.

<Info>
  This page is the command reference. For the full integration guide — plugin
  examples for GitHub Actions and Buildkite, AWS credential options, and exit
  codes — see [CI/CD Integration](/deployment/ci-cd).
</Info>

## Overview

The `fjall ci` command family covers everything a pipeline needs: scaffolding
the workflow file (`setup`), proving the credential works before the first run
(`verify`, `status`), managing CI deploy tokens (`token`), and the single
non-interactive entry point both official plugins invoke under the hood
(`run`).

Pipelines authenticate with a **CI deploy token** (`fjall_dk_`), minted in the
web app under **Settings → CI/CD Tokens** and stored as the `FJALL_API_KEY`
secret. Minting is session-only — the CLI cannot create one — but everything
after the mint works from the CLI.

## Subcommands

### Set up a pipeline

```bash theme={null}
fjall ci setup --app api --plan   # report detected provider/app + target path
```

Detects your CI provider and application, resolves the deploy target, and
writes the plugin-form workflow file for GitHub Actions or Buildkite.

| Option                   | Description                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------- |
| `--provider <provider>`  | CI provider: `github` or `buildkite` (default: detected)                              |
| `--app <name>`           | Application to deploy (default: detected)                                             |
| `--repo <owner/name>`    | Repository (default: detected)                                                        |
| `--environment <env>`    | Deploy to the unique account on this stage; also restricts the token                  |
| `--target <name>`        | Deployment target: a `fjall target list` name, pinned as the workflow's deploy-target |
| `--expires <duration>`   | Token expiry duration, for example `90d`, `24h`, `30m` (default: `90d`)               |
| `--queue <queue>`        | Buildkite agent queue for the deploy step (Buildkite provider only)                   |
| `--workflow-path <path>` | Workflow file path (default: provider convention)                                     |
| `--plan`                 | Detect, resolve and preview only — mint and write nothing                             |
| `--force`                | Overwrite an existing workflow file                                                   |

<Note>
  Without `--plan`, `setup` attempts to mint the deploy token before it writes
  anything — and the API only permits minting from an interactive browser
  session, so the command fails with guidance and writes no workflow file.
  Mint the token in the web app (**Settings → CI/CD Tokens**) and copy the
  workflow YAML from the [CI/CD Integration](/deployment/ci-cd) examples.
</Note>

### Verify readiness

```bash theme={null}
fjall ci verify --app api   # exit 0 = ready, exit 1 = at least one check failed
```

Dry-runs the auth handshake before your first pipeline run: credential,
principal kind, expiry runway, and (with `--app`) that the application
resolves. Each failing check prints a directional fix.

### Check token readiness

```bash theme={null}
fjall ci status
```

Summarises your CI deploy credentials: how many tokens exist, which are
expiring or expired, and what kind of credential the current session holds.

### Manage tokens

```bash theme={null}
fjall ci token list
fjall ci token revoke <id> --reason "pipeline decommissioned"
```

`fjall ci token create` exists for completeness, but the API refuses
non-session mints: minting a deploy token is admin-equivalent and requires the
web app (**Settings → CI/CD Tokens**). The command prints that guidance when
refused. `list` and `revoke` work with any authenticated credential.

| `create` option        | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `--name <name>`        | Token name (default: `ci-deploy`)                   |
| `--app <app>`          | Restrict to an application ID                       |
| `--environment <env>`  | Restrict to an environment name                     |
| `--expires <duration>` | Expiry duration, for example `90d` (default: `90d`) |
| `--tag <tag>`          | Source tag for auditing                             |

### Run a deploy from CI

```bash theme={null}
fjall ci run deploy api
```

`fjall ci run <deploy|destroy|build> <target> [service]` is the single CI
entry point — the same command both official plugins invoke. It forces
non-interactive output, skips confirmation prompts, and rejects flags that
don't apply to the command you're running.

The full flag table, exit codes (including `2` plan-pending and `4`
destruction-gate), and provider examples live in
[CI/CD Integration → Raw CLI Usage](/deployment/ci-cd#raw-cli-usage-any-ci-system).

## Next steps

<CardGroup cols={2}>
  <Card title="CI/CD Integration" icon="gears" href="/deployment/ci-cd">
    Full pipeline guide: plugins, tokens, AWS credentials, exit codes.
  </Card>

  <Card title="Engine Compatibility" icon="scale-balanced" href="/deployment/engine-compatibility">
    How `cli-version` keeps the CI-installed CLI aligned with your constructs.
  </Card>
</CardGroup>