# CLI commands

`seekrit <command> [options]`. At runtime a **service token selects the org, app,
and environment** — so `seekrit run`/`export` need no config file. Management
commands select their target with `--org`/`--app`/`--group`/`--env` flags,
falling back to the optional `seekrit.json` written by `seekrit init`.

## Environment variables

| Variable | Purpose |
| --- | --- |
| `SEEKRIT_TOKEN` | Service token (`skt_…`). Carries its bound org + app + environment. |
| `SEEKRIT_DEV_USER` | Dev identity email (local API with `AUTH_MODE=dev`). |
| `SEEKRIT_API_URL` | API base URL (overrides saved config). |
| `SEEKRIT_PASSPHRASE` | Passphrase to unlock your private key non-interactively. |

Precedence: environment variables override values saved by `seekrit login` in
`~/.config/seekrit/config.json`.

## Auth & identity

### `seekrit login`

Persist credentials to the config file.

| Flag | Description |
| --- | --- |
| `--token <token>` | Service token (`skt_…`). |
| `--dev-user <email>` | Dev identity (local `AUTH_MODE=dev`). |
| `--api-url <url>` | API base URL. |

### `seekrit whoami`

Show the authenticated identity. For a service token, prints its bound
`org/app/env` scope.

### `seekrit keys setup`

Generate your P-256 keypair and upload your public key plus a passphrase-encrypted private key.
Run once per account. Honors `SEEKRIT_PASSPHRASE`, otherwise prompts.

## Resources

### `seekrit init`

`--org <slug> --app <slug>` — write `seekrit.json` naming default org + app for
management commands. **Environment-independent and safe to commit** — it never
pins an environment (the token does that at runtime).

### `seekrit org create`

`--name <name> --slug <slug>` — create an organization (you become owner).

### `seekrit app create`

`[--org <slug>] --name <name> --slug <slug>` — create an application in an org.

### `seekrit env create`

`[--org <slug>] --app <slug> --name <name> --slug <slug>` — create an application
environment. Generates the environment's data key locally and wraps it to your public key.

### `seekrit group create`

`[--org <slug>] --name <name> --slug <slug>` — create a **group**: a reusable
secret bag shared across applications.

### `seekrit group env create`

`[--org <slug>] --group <slug> --name <name> --slug <slug>` — create a group
environment (a per-slug value set / variant). Generates its data key locally.

## Composition (`env groups`)

Compose shared groups into an application environment. At resolve time each group
is matched to the environment whose slug matches the app environment's (or a
`--with` override).

| Command | Description |
| --- | --- |
| `seekrit env groups add --app <slug> --env <slug> --group <slug> [--position <n>]` | Compose a group (higher position wins). |
| `seekrit env groups list --app <slug> --env <slug>` | List composed groups and their precedence. |
| `seekrit env groups rm --app <slug> --env <slug> --group <slug>` | Remove a group. |

## Secrets

Every `secrets` command targets one environment via flags: an application
environment (`--app --env`, or the config's app + `--env`) or a group environment
(`--group --env`). `--org` is inferred from `seekrit.json` or a lone org.

| Command | Description |
| --- | --- |
| `seekrit secrets list --env <slug> [--app <slug>\|--group <slug>]` | List secret names, versions, update times (no values). |
| `seekrit secrets get <name> --env <slug> …` | Decrypt and print one value. |
| `seekrit secrets set <name> [value] --env <slug> …` | Encrypt and store a value. Reads stdin if `value` is omitted or `-`. |
| `seekrit secrets rm <name> --env <slug> …` | Delete a secret. |

## Running & exporting

Both resolve a **layered** environment for the current principal:

```
group secrets  <  app-env secrets  <  .env file  <  process env   (highest wins)
```

With a service token, org/app/env come from the token. As a logged-in user, pass
`--app --env` (and `--org` if ambiguous).

| Flag | Applies to | Description |
| --- | --- | --- |
| `--with <group>=<slug>` | run, export | Resolve one group at a different slug for this invocation (repeatable). |
| `--env-file <path>` | run, export | A `.env` file to overlay; repeatable; defaults to `.env`. |
| `--explain` | run, export | Print each variable's source layer to stderr (never values). |

### `seekrit run -- <command…>`

Run a command with the resolved environment injected. Everything after `--` is the command.

```bash
SEEKRIT_TOKEN=skt_… seekrit run -- ./start-server
# swap only the auth group to its staging slice for this boot:
seekrit run --with auth-providers=staging -- pnpm dev
```

Resolving seekrit secrets is **best-effort**: if no credentials are configured
or seekrit can't be reached (network, auth, or decryption failure), `run` logs a
warning to stderr and still launches the command with just the `.env` overlay
and `process.env`. This mirrors the [`seekrit-run` launcher](#seekrit-run-launcher).
(`seekrit export` does not degrade — it errors if it can't resolve the secrets.)

### `seekrit export`

Print the resolved secrets (managed layers + `.env`, without `process.env`).
`--format <dotenv|json|shell>` (default `dotenv`).

## `seekrit-run` launcher

`seekrit-run` is a separate, compiled single-file binary — a dependency-free
`seekrit run` for machines (containers, CI, agents). It is **service-token
only** and reproduces `seekrit run`'s precedence and `.env` parsing exactly. See
the [launcher guide](/docs/guides/run) for install and container usage.

```
seekrit-run [OPTIONS] [--] <command> [args...]
seekrit-run run [OPTIONS] [--] <command> [args...]   # `run` is optional
```

| Flag | Default | Description |
| --- | --- | --- |
| `-t, --token <skt_…>` | `SEEKRIT_TOKEN` (env or `.env`) | Service token. |
| `--api-url <url>` | `SEEKRIT_API_URL` or `https://api.seekrit.dev` | API base URL. |
| `-e, --env-file <path>` | `.env` | A `.env` file to overlay (repeatable). |
| `--no-env-file` | | Do not load the default `.env`. |
| `--with <group=env>` | | Override one composed group's slice (repeatable). |
| `--explain` | | Print each variable's source to stderr (names only). |

Like `seekrit run`, it degrades gracefully: a missing/malformed token or an
unreachable API is logged to stderr, and the command runs with just `.env` +
the live environment. Exit codes: `2` usage error, `1` unreadable explicit
`--env-file`, `127` command not found; otherwise the command's own exit code
(Unix `exec`). Honors `HTTPS_PROXY` / `ALL_PROXY`. Note its default API URL is
the hosted `https://api.seekrit.dev` (the Node CLI defaults to your saved
config).

## Access

### `seekrit grant`

Grant an environment's key to a principal. Target the environment with
`--env` plus `--app` or `--group`; then exactly one of:

| Flag | Description |
| --- | --- |
| `--user <email>` | Grant to an org member (must have completed key setup). |
| `--token <tokenId>` | Grant to a service token (`skt_…`). |

## Service tokens

| Command | Description |
| --- | --- |
| `seekrit token create --name <name> --app <slug> --env <slug> [--allow <group>=<slug>] [--no-grant]` | Mint a **runtime** token bound to an app environment; prints it once. Auto-grants that env's key and every composed group's matching slice. `--allow` pre-authorizes an alternate group slice for `run --with`; `--no-grant` skips granting. |
| `seekrit token create --name <name> --admin [--org <slug>]` | Mint an **admin** token: org-scoped, no env binding, passes admin-gated routes (create apps/groups/envs, compose, grant, mint tokens). For headless provisioning by agents/automation. Only an admin caller may create one. |
| `seekrit token list [--org <slug>]` | List tokens with role, status, and last-used time. |
| `seekrit token revoke <tokenId> [--org <slug>]` | Revoke a token. |

An admin token can also be bound to an environment (pass `--admin --app --env`)
to both provision structure **and** decrypt that environment.

## Agent integration

### `seekrit mcp`

Run an [MCP](https://modelcontextprotocol.io) server over stdio so AI agents
(Claude Code and other MCP clients) can drive seekrit as tools. It reads the
same credentials as every other command (`SEEKRIT_TOKEN` / `SEEKRIT_DEV_USER`,
or the saved config).

```bash
# Register with Claude Code (token selects the org; admin token enables provisioning):
SEEKRIT_TOKEN=skt_… claude mcp add seekrit -- seekrit mcp
```

All decryption happens **locally**, in this process — the server exposes the
tools that touch plaintext (secret values, data keys, decryption-capable
grants), which is why it runs on your machine rather than a hosted endpoint.
Tools include `create_org`/`create_app`/`create_env`, `set_secret`/`get_secret`,
`create_token`, `grant_env`, and `run_command` (inject secrets into a subprocess
without returning their values). Because stdin is the transport, user-auth
sessions that decrypt need `SEEKRIT_PASSPHRASE` set (token auth needs nothing
extra). Prefer `run_command` over `get_secret` with `reveal:true` so plaintext
never enters the agent's context.

## Audit

### `seekrit audit`

Print the org's audit trail. `[--org <slug>] --limit <n>` (default 50).