← Blog ·

Getting Started with Koove CLI: From npm install to Your First Encrypted Secret in 5 Minutes

Why a secrets manager CLI matters right now

In the age of AI-generated code, secrets end up hardcoded more often, not less. Your AI assistant pastes an API key into a config file because that's the fastest way to make the demo work, and it stays there until someone finds it — usually in a public repo. If you want the full picture of why this happens and how to structure your workflow around it, we cover it in more depth in /ai-security.

Koove CLI exists to remove the temptation entirely: your code (and your AI assistant) references secrets by name, never by value. The actual value lives encrypted, and only decrypts on devices or backends that have proven who they are.

This koove cli tutorial gets you from zero to your first encrypted secret in about five minutes. No cert chains, no dashboards you have to click through — just the terminal.

Step 1: Install

npm install -g @koove/cli

Verify it installed correctly:

koove --version

If you'd rather not install globally, use npx for one-off commands:

npx @koove/cli set STRIPE_SECRET_KEY sk_live_xxx --env prod

Step 2: Create an account and log in

You need a Koove account before the CLI can talk to anything. Sign up at /register — it takes under a minute, no credit card required for the free tier (check current limits on /plans).

Once you have an account:

koove login

This opens a browser window to authenticate, then stores a local session token on your machine. Nothing sensitive from your vault is cached locally — the token only lets your CLI request encrypted blobs, which still have to pass through the decryption flow.

Step 3: Store your first secret

Say you're wiring up Stripe in a Node project. Instead of dropping the key into .env and hoping nobody commits it:

koove set STRIPE_SECRET_KEY sk_live_51J... --env prod

You can create as many environments as you want — dev, staging, prod, ci, whatever matches your pipeline:

koove set STRIPE_SECRET_KEY sk_test_51J... --env dev

List what's stored (values are never printed, only names and metadata):

koove list --env prod

NAME                 ENV     UPDATED
STRIPE_SECRET_KEY    prod    2024-06-11 10:32
DATABASE_URL         prod    2024-06-10 18:04

Step 4: Read it back

To fetch a secret's value directly (useful for debugging or one-off scripts):

koove get STRIPE_SECRET_KEY --env prod

More commonly, you don't want the value printed anywhere — you want it injected into a process's environment at runtime:

koove run --env prod -- node server.js

koove run resolves every secret your app needs, decrypts them in memory, and passes them as environment variables to the child process. Nothing touches disk, nothing lands in your shell history.

Step 5: Use it from code

For backend services, the SDK is usually cleaner than shelling out from a script. Full reference lives in /docs/sdk, but the basic pattern is:

import { Koove } from "@koove/sdk";

const koove = new Koove({ env: "prod" });

async function getStripeClient() {
  const key = await koove.get("STRIPE_SECRET_KEY");
  return new Stripe(key);
}

The SDK authenticates the backend as a verified consumer (via a service credential you generate once), then decrypts the secret locally after the server proves its identity. Your code never sees the raw ciphertext blob, and the Koove backend never sees the decrypted value.

What's actually happening under the hood

Koove uses envelope encryption built on open-source primitives: X25519 for key exchange, AES-256-GCM for the payload. When you run koove set, the value is encrypted client-side before it ever leaves your machine. The Koove server stores ciphertext only — it has no key that lets it read your secrets.

Decryption happens only on consumers that have proven they are who they claim to be:

  • Mobile clients authenticate via Apple App Attest or Google Play Integrity, plus biometrics, before a key is released.
  • Backend services authenticate with a service credential tied to that backend.

This is meaningfully different from storing secrets in a .env file or a CI variable that any process on the box can read — but it's not magic. Koove reduces where plaintext secrets can leak; it doesn't make a compromised device or a leaked service credential harmless. If an attacker gets a valid, attested session, they get whatever that session is authorized to read — same as any access control system.

One honest limitation worth stating plainly: if a secret has already been decrypted and copied out of a compromised environment, revoking access in Koove stops future reads — it doesn't reach back and un-deliver a copy that already left. Rotate the underlying secret (e.g., generate a new Stripe key) if you suspect exposure; revocation and rotation are different actions.

Environments and rotation

Keep environments strictly separate. A common mistake is sharing a single prod credential across dev and staging "temporarily." Don't. Use:

koove set STRIPE_SECRET_KEY sk_test_xxx --env dev
koove set STRIPE_SECRET_KEY sk_live_xxx --env prod

When you rotate a key at the provider (Stripe, AWS, whatever), update Koove immediately:

koove set STRIPE_SECRET_KEY sk_live_new... --env prod

Old ciphertext is superseded; consumers pulling fresh values via koove run or the SDK get the new one automatically.

Wiring your AI assistant in

If you're using Cursor, Copilot, or a custom agent to scaffold code, tell it explicitly to call secrets by name and never paste literal values:

koove set NAME value --env prod

Then in generated code, the assistant should only ever write process.env.NAME or koove.get("NAME") — never the literal string. This is the core habit that keeps secrets out of your commit history in the first place, and it's the workflow we go into more in /ai-security.

Where to go next

  • Full command reference and SDK docs: /docs/sdk
  • Plan limits and team features: /plans
  • Common questions (offline access, team sharing, key rotation): /faq

Wrap-up

Five minutes gets you a working CLI, one encrypted secret, and a habit that's hard to break: names in code, values in Koove. If you're building anything with AI-assisted tooling right now, this is worth doing before your first commit, not after your first leak. Head to /register and run your first koove set.

AI-generated code

Your AI writes the code. Who guards the secrets?

The most common security failure in AI-generated apps is exposed credentials. With Koove, your own assistant stores every token from the CLI — encrypted on your machine, never in the code or the repo.

Start freeSecurity for AI code →
Getting Started with Koove CLI: From npm install to Your First Encrypted Secret in 5 Minutes