# CLI

The `seekrit` CLI injects a decrypted, layered environment into your processes. It decrypts
locally using the same keys as the web app — a service token's embedded key, or your
passphrase-unlocked private key. 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

The CLI reads credentials from config or environment variables:

- `SEEKRIT_TOKEN` — a service token (`skt_…`), for CI and machines.
- `SEEKRIT_DEV_USER` — a dev identity (local API with `AUTH_MODE=dev`).
- `seekrit login` persists these to `~/.config/seekrit/config.json`.

```bash
# machine / CI
export SEEKRIT_TOKEN=skt_...
export SEEKRIT_API_URL=https://api.your-seekrit.example

# or, for local development
seekrit login --dev-user you@example.com --api-url http://localhost:8787
```

## Linking a project

`seekrit init` writes a `seekrit.json` naming 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.

```bash
seekrit init --org acme --app storefront
```

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

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

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

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

## Building the CLI

From the monorepo, the CLI builds to a self-contained bundle:

```bash
pnpm --filter @seekrit/cli build
node apps/cli/dist/index.js --help
```