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