@seekrit/cli 0.0.1 → 0.2.0

package/README.md

@@ -0,0 +1,131 @@
+# @seekrit/cli
+
+The `seekrit` command-line client for [seekrit](https://seekrit.dev) — an
+end-to-end encrypted secrets manager. Secrets are encrypted and decrypted **on
+your machine**; the API only ever stores ciphertext. The CLI is the piece that
+holds your keys, so plaintext, private keys, and passphrases never leave the
+device.
+
+Use it to manage secrets from a terminal, inject them into a process
+(`seekrit run`), export them for another tool (`seekrit export`), and give CI or
+agents scoped access via service tokens.
+
+## Install
+
+```sh
+npm  install -g @seekrit/cli    # or: pnpm add -g @seekrit/cli
+seekrit --help
+```
+
+Requires Node ≥ 20. You can also run it without installing via
+`npx @seekrit/cli …`.
+
+## Quickstart
+
+```sh
+# 1. Authenticate (a service token, or a dev identity for a local API)
+seekrit login --token skt_…
+
+# 2. Set up your encryption keypair (protected by a passphrase that never
+#    leaves this machine). Only needed once per account.
+seekrit keys setup
+
+# 3. Link the current directory to an org / app / environment. Writes
+#    seekrit.json, which is safe to commit.
+seekrit init --org acme --app storefront --env production
+
+# 4. Work with secrets
+seekrit secrets set DATABASE_URL 'postgres://…'
+seekrit secrets list
+seekrit run -- ./server            # runs ./server with secrets in its env
+seekrit export --format dotenv > .env
+```
+
+New to seekrit? The [Quickstart](https://seekrit.dev/docs/quickstart) walks
+through creating the org/app/environment from scratch, and the
+[CLI guide](https://seekrit.dev/docs/guides/cli) covers day-to-day workflows.
+
+## Commands
+
+Run `seekrit <command> --help` for full flags. The
+[CLI reference](https://seekrit.dev/docs/reference/cli) is the complete list.
+
+| Command | What it does |
+| --- | --- |
+| `login [--token \| --dev-user] [--api-url]` | Save credentials to the global config. |
+| `whoami` | Show the authenticated identity and org membership. |
+| `keys setup` | Generate your keypair and protect it with a passphrase. |
+| `init --org --app --env` | Link this directory to an environment (`seekrit.json`). |
+| `org create` / `app create` / `env create` | Create organizations, apps, and environments. |
+| `secrets list` | List secret names (never values). |
+| `secrets get <name>` | Decrypt and print one secret value. |
+| `secrets set <name> [value]` | Encrypt and store a secret (reads stdin if value is omitted or `-`). |
+| `secrets rm <name>` | Delete a secret. |
+| `run <command…>` | Run a command with decrypted secrets in its environment. |
+| `export [--format dotenv\|json\|shell]` | Print decrypted secrets in the chosen format. |
+| `grant [--user \| --token]` | Grant a member or service token access to the linked environment. |
+| `token create` / `list` / `revoke` | Manage service tokens for CI, Docker, and agents. |
+| `audit [--limit]` | Show the org audit trail. |
+
+`seekrit run` passes flags through to the child command — put them after `--`
+(e.g. `seekrit run -- node app.js --port 3000`). `secrets set NAME -` reads the
+value from stdin, so you can pipe: `printf '%s' "$VALUE" | seekrit secrets set NAME -`.
+
+## Service tokens (CI, Docker, agents)
+
+A service token carries its own private key in the token string; the server
+stores only a hash and the public key, so it can be granted access without a
+passphrase.
+
+```sh
+seekrit token create --name ci-deploy --grant     # prints the token once — save it
+SEEKRIT_TOKEN=skt_… seekrit run -- ./deploy.sh
+SEEKRIT_TOKEN=skt_… seekrit export --format dotenv
+seekrit token revoke <tokenId>
+```
+
+See the [service tokens guide](https://seekrit.dev/docs/guides/service-tokens).
+
+## Configuration
+
+Credentials and defaults are read from (highest precedence first) environment
+variables, then the global config file, then built-in defaults.
+
+| Variable | Overrides | Notes |
+| --- | --- | --- |
+| `SEEKRIT_TOKEN` | `token` | Service token (`skt_…`). |
+| `SEEKRIT_DEV_USER` | `devUser` | Dev-mode identity for a local API running with `AUTH_MODE=dev`. |
+| `SEEKRIT_API_URL` | `apiUrl` | API base URL (default `http://localhost:8787`). |
+| `SEEKRIT_PASSPHRASE` | — | Unlocks your private key non-interactively (CI, scripts). |
+
+- **Global config** — written by `seekrit login` to
+  `$XDG_CONFIG_HOME/seekrit/config.json` (default
+  `~/.config/seekrit/config.json`), created with `0600` permissions.
+- **Project config** — `seekrit.json`, written by `seekrit init` and resolved by
+  walking up from the current directory. Safe to commit; it holds only
+  org/app/environment identifiers, never secrets.
+
+## Local development
+
+From the repo root, after building once (`pnpm --filter @seekrit/cli build`),
+you can run the local build against a dev API:
+
+```sh
+alias seekrit="node $PWD/apps/cli/dist/index.js"
+export SEEKRIT_PASSPHRASE=dev-only-passphrase
+seekrit login --dev-user you@example.com --api-url http://localhost:8787
+```
+
+See the root [README](../../README.md) for the full end-to-end local loop.
+
+### Build
+
+The CLI is bundled with [tsdown](https://tsdown.dev). Workspace packages
+(`@seekrit/*`) are inlined so the published package's only runtime dependency is
+`commander`.
+
+```sh
+pnpm build       # bundle to dist/index.js
+pnpm dev         # rebuild on change (tsdown --watch)
+pnpm typecheck   # tsc --noEmit
+```