# CLI

The `seekrit` CLI injects a decrypted, layered environment into your processes: run
`seekrit run -- <command>` and it resolves, decrypts, and execs your command with secrets
already in `process.env`. It decrypts locally using the same keys as the web app — a service
token's embedded key, or your passphrase-unlocked private key — and at runtime a **service
token selects the org, app, and environment**, so `seekrit run` needs nothing else.

For an exhaustive list of commands and flags, see the [CLI reference](/docs/reference/cli).

## Authentication

Two credentials, one for each kind of caller.

### You, at a terminal: `seekrit login`

Run it with no arguments. The CLI prints a URL and a pairing code, opens the URL
when you press `[Enter]`, and you authorize the device in the dashboard — entering
your authenticator code again if you have one, since this creates a long-lived
credential.

```bash
seekrit login
```

```
Sign in to seekrit to authorize this device (you@laptop).

  https://app.seekrit.dev/cli/login?code=RFH4R-C36QG

  code: RFH4R-C36QG   — check it matches the one in your browser

Press [Enter] to open it in your browser (Ctrl-C to cancel)…
✓ Signed in as you@example.com — this device is authorized for 90 days.
```

The saved session acts as **you**: every org you're a member of, at your role — so
there's no org, app, or environment to pick, and management commands work the same
as the dashboard. Reading a secret's *value* still unlocks your own private key with
your passphrase on that machine, which is why a stolen session file reveals no
secrets. `seekrit logout` revokes it; so does the CLI sessions list under
**account → security**.

On a headless box or over SSH, add `--no-browser` and open the printed URL wherever
you do have a browser.

### Machines and CI: a service token

A **service token** (`skt_…`) is bound to one application environment and carries
its own key, so it decrypts unattended with no passphrase and no browser. Mint one
in the web console (or with the CLI once you hold an admin token).

- `SEEKRIT_TOKEN` — the service token. Machines and CI read it from the environment.
- `SEEKRIT_API_URL` — override the API base URL (defaults to `https://api.seekrit.dev`).
- `seekrit login --token skt_…` persists it to `~/.config/seekrit/config.json`.

```bash
# machine / CI
export SEEKRIT_TOKEN=skt_...

# or persist it to the config file
seekrit login --token skt_...
```

Agents take a third path — one machine credential that drives both MCP planes; see
[AI agents](/docs/guides/ai-agents).

## Finding your way around

Signed in on a machine you've never used before, start by asking what you can reach:

```bash
seekrit whoami                  # who you are, and via which credential
seekrit org list                # every org you belong to, and your role
seekrit org tree                # its apps and groups, with their environments
```

`org tree` is usually enough to orient yourself. When you need detail, every resource has a
`show`, and each one answers the question you actually have:

```bash
seekrit app show storefront     # its environments — and whether you can decrypt each
seekrit env show --env production
```

`app show` marks each environment `can decrypt` or `no key`. That column is the answer to
"why does `secrets get` fail here?" — secret **names** are visible to any member, but a
**value** needs a key grant. `env show` goes further: which groups the environment composes and
in what order, who holds a key for it, and how many secrets it has.

To see and change who can read an environment:

```bash
seekrit grant list --app storefront --env production
seekrit grant --app storefront --env production --user teammate@example.com
seekrit grant rm --app storefront --env production --user former@example.com
```

Every listing prints an aligned table at a terminal and plain tab-separated rows when piped, so
`seekrit app list | cut -f1` works. Add `--json` anywhere you'd rather have the API's own
response.

## Setting a project up

`seekrit init` takes a directory from wherever it is to linked. With no credential on the machine
it signs up first — a workspace and a machine credential, no account, no browser — then creates an
app named after the project with a `development` environment, and writes `seekrit.json`. With a
credential it skips straight to the app and environment, and with both already in place it only
writes the file, so re-running it is harmless.

```bash
npx -y @seekrit/cli init --org-name "Acme Storefront" --yes   # from nothing
seekrit init                                                  # already signed in
seekrit init --org acme --app storefront                      # link an existing org/app
```

Two optional steps fold in: `--from-env .env` imports an existing file into the environment (delete
the file afterwards — the values live in seekrit now), and `--invite you@example.com` invites a
person as admin so they can claim the workspace on first sign-in.

`seekrit.json` names the default org and app for management commands. It is
**environment-independent** — it never pins an environment — so it's safe to commit and behaves the
same everywhere. The environment is chosen at runtime by the service token (or the `--env` flag when
you run commands interactively).

## Running with a service token

This is the primary path: the token carries its org, app, and environment.

```bash
export SEEKRIT_TOKEN=skt_...
seekrit run -- ./start-server          # resolves & injects; no flags needed
seekrit export --format dotenv > .env
```

The resolved environment is **layered**, lowest precedence first:

```
group secrets  <  app-env secrets  <  .env file  <  process env
```

Add `--explain` to see where each variable came from, and `--with <group>=<slug>` to swap a single
group's slice for one run (see [Environments & groups](/docs/guides/environments)).

## Running interactively (as a user)

Without a token, target the environment explicitly:

```bash
seekrit run --app storefront --env production -- npm run dev
seekrit export --app storefront --env production --format shell
```

For a production script, lease a temporary Postgres user from a registered
dynamic-secret target:

```bash
seekrit run --with ampersand=production \
  --lease DATABASE_URL=ampersand-prod --lease-ttl 30m \
  -- tsx myscript.ts
```

The leased URL overrides `DATABASE_URL` from every other source. Seekrit logs
the temporary username, runs the script, then revokes the lease on exit or
Ctrl-C. Provisioning failures prevent the script from starting. The default
TTL is 30 minutes and provides a fallback for interrupted cleanup. This needs
admin access and a configured Postgres target; see the
[lease lifecycle and cleanup limits](/docs/reference/cli#temporary-database-users).

## Reading & writing individual secrets

Every `secrets` command targets an environment with `--env` plus `--app` (or `--group`); `--org`
comes from `seekrit.json` or a lone org.

Authenticated with a **service token**, drop the flags entirely — the token is bound to one
environment and the command uses it:

```bash
seekrit secrets list                       # the token's own environment
seekrit secrets set DATABASE_URL 'postgres://…'
```

As a logged-in user, name the target:

```bash
seekrit secrets list --app storefront --env production
seekrit secrets get STRIPE_KEY --app storefront --env production
seekrit secrets set DATABASE_URL 'postgres://…' --app storefront --env production
printf '%s' "$TOKEN" | seekrit secrets set GITHUB_TOKEN --app storefront --env production
seekrit secrets rm OLD_KEY --group common --env production   # a group's secret
```

A value may reference another secret in the same environment — stored literally
and assembled when it is read, so a rotation flows through automatically:

```bash
seekrit secrets set DB_HOST db.internal --app storefront --env production
seekrit secrets set DATABASE_URL 'postgres://app@${DB_HOST}/app' --app storefront --env production
seekrit secrets get DATABASE_URL --app storefront --env production
# postgres://app@db.internal/app        (--raw prints the stored text)
```

See [secret references](/docs/guides/references) for the full rules.

## Undoing a bad write

Each `set` appends a version, so you can always look back — and go back:

```bash
seekrit secrets history DATABASE_URL --app storefront --env production
seekrit secrets get DATABASE_URL --version 2 --app storefront --env production  # peek first
seekrit secrets restore DATABASE_URL 2 --app storefront --env production
```

`history` prints when each version was saved, who saved it, and which ones were
themselves restores — never the values. `restore` writes the old value back as
a *new* version, so nothing is lost and the rollback can be rolled back. See
[point-in-time restore](/docs/reference/cli#point-in-time-restore) for the
details.

## Importing a `.env` file

Bulk-load an existing `.env` into an environment. Each `KEY=VALUE` is encrypted
locally and stored; names that already exist are overwritten. Pass `--dry-run`
first to preview which names are new versus updated (nothing is written).

```bash
seekrit secrets import --app storefront --env production --dry-run   # preview (default .env)
seekrit secrets import .env.production --app storefront --env production
cat .env | seekrit secrets import - --group common --env production  # from stdin, into a group
```

The importer parses the same `.env` syntax as [`seekrit run`](/docs/guides/run)
(`export` prefixes, `#` comments, single/double quotes). An invalid variable name
aborts the whole import before anything is written.

## Unlocking (users)

When authenticated as a user (not a service token), decryption needs your passphrase to unlock
your private key. Set it non-interactively for scripts:

```bash
export SEEKRIT_PASSPHRASE='…'
```

Omit it and the CLI prompts. Service tokens don't need a passphrase — their key is in the token.

> **Tip:** In CI and containers, prefer a **service token** granted only the environments it needs. It
>   requires no passphrase and can be revoked independently. See
>   [Service tokens](/docs/guides/service-tokens).

## Installing the CLI

The CLI is published to npm. Install it globally with your package manager:

```bash
npm install -g @seekrit/cli
seekrit --help
```

### As a container

The CLI also ships as a multi-arch Docker image —
[`seekritdev/cli`](https://hub.docker.com/r/seekritdev/cli), mirrored to
`ghcr.io/seekritdev/cli` — for CI runners and agent sandboxes. Same bytes and
tags either way; prefer `ghcr.io` from CI, which has no anonymous pull rate
limit. Its entrypoint is `seekrit`, so pass subcommands straight
through:

```bash
docker run --rm \
  -e SEEKRIT_TOKEN=skt_... \
  -v "$PWD:/work" -w /work \
  seekritdev/cli run -- ./deploy.sh
```

Pin a release (`seekritdev/cli:0.10.0`) or track `:edge`. For a Node-free
runtime image, prefer the [`seekrit-run`](/docs/guides/run) launcher instead.

## Common questions

### How do I inject secrets into a command with the seekrit CLI?

Set SEEKRIT_TOKEN to a service token and run seekrit run -- <command>; the token carries its org, app, and environment, so no other flags are needed. Without a token, name the target explicitly: seekrit run --app <app> --env <env> -- <command>.

### How do I use the seekrit CLI in CI without seekrit login?

Export SEEKRIT_TOKEN with a service token bound to the environment CI needs. It decrypts unattended with no passphrase and no browser, and every seekrit command reads it from the environment instead of a saved session.

### How do I undo a bad secret write from the CLI?

Run seekrit secrets history NAME --app <app> --env <env> to see every version and who saved it, then seekrit secrets restore NAME <version> --app <app> --env <env>. Restore writes the old value back as a new version, so the rollback itself can be rolled back.

### How do I import an existing .env file with the CLI?

Run seekrit secrets import .env --app <app> --env <env>, or add --dry-run first to preview which names are new versus updated without writing anything. It parses the same syntax seekrit run does — export prefixes, # comments, and quoted values — and aborts the whole import on an invalid variable name.

### How do I give a script a temporary database credential instead of a standing one?

Use seekrit run --lease DATABASE_URL=<target> --lease-ttl 30m -- <command> against a registered dynamic-secret target. The leased URL overrides DATABASE_URL from every other source, and seekrit revokes it on exit or Ctrl-C, with the TTL as a fallback for interrupted cleanup. This needs admin access and a configured Postgres target.
