vaultlier

Typed runtime client, CLI, and type generation for Vaultlier - a sealed, centrally hosted configuration vault. Replaces the .env workflow without writing secret values to disk.

Install

npm install vaultlier

Quick start

npx vaultlier init
npx vaultlier pull --env=prod
npx vaultlier audit

init walks a new developer through the whole setup: it installs the dependency if needed, offers a browser login when you have no account credentials yet, lets you pick an existing project with the arrow keys (or create a new one), and asks for an API key - press Enter to skip if you don't have one yet. It always writes the metadata-only vaultlier.config.json (schema), and optionally generates a typed SDK client. When you accept the prompt, the client is generated at lib/vaultlier/vaultlier.ts by default (override with --client=<path>); decline (or pass --no-client) to wire the SDK by hand with import { createClient } from 'vaultlier'. The chosen path is recorded in vaultlier.config.json ("client"), so later commands only regenerate the client when you opted in. Existing projects that still have vaultlier.json continue to work as legacy config files. Fully non-interactive setup still works: npx vaultlier init --project-id=<id> --api-key=<key> (generates the client unless --no-client is passed).

During init, Vaultlier also ensures .env contains a self-hosted portal master key placeholder and instructions:

# Vaultlier portal master key. Generate with `vaultlier generate-key` or any other 32-byte base64 method.
VAULT_MASTER_KEY=""

If .env already exists, the block is appended. If VAULT_MASTER_KEY is already present, Vaultlier leaves it untouched.

Login and account

npx vaultlier login    # prints a URL + code; approve it in the browser
npx vaultlier logout   # removes the locally stored account token

login uses the device-code flow: the CLI shows a verification link and a short code, you approve it in the browser, and the CLI receives an account token. The token is stored per-user in ~/.vaultlier/auth.json (owner-only permissions), never inside a repository, and only authorizes account operations such as listing and creating projects - it is not a project API key and cannot read secrets.

Local configuration

npx vaultlier config set project=prj_29ec67d64dd1
npx vaultlier config set apiKey=vlt_live_...
npx vaultlier config get      # current settings, API key masked
npx vaultlier config verify   # re-validates the project id + key with the portal

config set project=... updates vaultlier.config.json (or the active legacy vaultlier.json) and regenerates the typed client when one was generated; config set apiKey=... updates only the local credential cache and never prints the key back. You can skip storing a key entirely and set VAULTLIER_API_KEY in the environment instead - the CLI and runtime resolve it automatically.

pull, push, and diff sync schema metadata (key names, types, scopes, environments - never values) with the Vaultlier portal using your API key. The portal base URL can be overridden with --api-url=<url> or VAULTLIER_API_URL for self-hosted deployments. Without an API key, pull falls back to regenerating from local metadata.

Generated config includes a $schema reference to https://schema.vaultlier.com/v2/vaultlier.schema.json for editor validation. No secret values are written to disk. The generated .env entry is an empty placeholder; store a real VAULT_MASTER_KEY only in trusted server environments.

Audit

Run a dependency-free local security scan from the repository root:

npx vaultlier audit
npx vaultlier audit --ai
npx vaultlier audit --output=security-report.html
npx vaultlier audit --no-ai

The CLI prints score analytics for project structure, exposed unprotected secrets, dependency posture, and framework surface. It writes a full local HTML report (vaultlier-audit-report.html by default) and records a metadata-only audit.lastRun summary in vaultlier.config.json or the active legacy config. The scanner detects common frameworks such as Next.js, NestJS, Vite, Angular, Express, and Node.js from package metadata and config files. It skips common generated output (node_modules, dist, .next, build directories, and similar caches).

Pass --ai to call the hosted /v1/audit/analyze endpoint for AI recommendations. The command uses the same project API key resolution order as other portal commands (explicit --api-key, VAULTLIER_API_KEY, then local credential cache). The portal routes to DeepSeek first, then OpenAI, then Anthropic based on configured provider keys. Pass --no-ai to force local-only scanning. The AI request sends sanitized audit metadata only - scores, framework names, finding titles, severities, paths, and recommendations. It does not upload source files, .env file contents, or secret values.

Set secret values

npx vaultlier set DATABASE_URL=postgres://prod-db/main --env=prod
npx vaultlier set STRIPE_SECRET=sk_live_... FEATURE_NEW_FLOW=true -e prod

set writes one or more KEY=VALUE pairs to a single environment. Keys must already exist in the schema (vaultlier push first) and be scoped to the target environment - both are checked locally before any value leaves your machine. Values are sealed server-side as new immutable versions; the CLI prints the new version numbers and never echoes the values back. Requires an API key with the member role or higher.

If the target environment does not exist yet, set offers to create it (pass --yes to skip the prompt, e.g. in CI):

npx vaultlier set DATABASE_URL=postgres://wip-db --env=working --yes

This declares the environment through an additive schema push (nothing is deleted), adopts the synced schema into the active config file, then writes the values against the new environment. An environment that exists locally but not in the portal is synced the same way automatically.

Remove secret values

npx vaultlier unset DATABASE_URL --env=prod
npx vaultlier unset STRIPE_SECRET FEATURE_NEW_FLOW --env=prod --yes

unset is the counterpart to set: it removes the stored values for one or more keys from a single environment. The schema metadata (key names, types, scopes) is left intact, so the keys can be re-set later. Because removal is unrecoverable, unset confirms before deleting unless you pass --yes (e.g. in CI). Values are never read, printed, or written to disk; a KEY=VALUE argument is accepted but the value is ignored, so a set line can be reused. The CLI reports which keys were removed (and which were not set). Requires an API key with the member role or higher.

CLI output

Commands print status-prefixed lines (check/warning/cross) and show a spinner while talking to the portal. Styling is zero-dependency and degrades gracefully: colors and the spinner activate only on an interactive terminal and are suppressed when output is piped or CI is set, so logs stay plain. NO_COLOR disables colors; FORCE_COLOR forces them. Spinners render on stderr, keeping stdout clean for scripting.

CLI flag conventions

Every value flag has a canonical --kebab-case long form; common ones also have a single-letter short form. Both --flag=value and --flag value work.

| Short | Long | Aliases | Used by | | ----- | -------------- | --------------- | -------------------------------------- | | -e | --env | --environment | pull, push, diff, set, unset | | -k | --api-key | --apiKey | all portal commands | | | --api-url | --apiUrl | all portal commands | | | --project-id | --projectId | init | | -p | --port | | dev | | -o | --output | | --generate, --generate-env, audit | | | --client | | init | | | --ai | | audit | | | --no-ai | | audit | | | --no-client | | init | | -g | --generate | | standalone | | -y | --yes | | prompts | | -f | --force | | init, generated .env | | -h | --help | | everywhere |

Inspect your config locally

npx vaultlier dev   # opens a local UI on http://127.0.0.1:9090

vaultlier dev starts a read-only dashboard, bound to loopback, that shows your project's metadata - key names, types, scopes, environments, and a masked API key. When an API key is available (via --api-key, VAULTLIER_API_KEY, or the local credential cache), it also fetches and displays values for the dev environment only; staging and prod values are never read or displayed, and nothing is written to disk. Without an API key the UI shows a warning and falls back to metadata only. Use --port=<n> to change the port.

Runtime usage

import { vault } from "./lib/vaultlier/vaultlier"; // generated client

const config = await vault({ environment: "prod" });
config.DATABASE_URL; // typed

Or construct a client directly:

import { createClient } from "vaultlier";

export const vault = createClient<{ DATABASE_URL: string }>({
  projectId: "prj_checkout_api",
});

API key resolution order

1. Explicit apiKey passed to the runtime call.
2. VAULTLIER_API_KEY in the hosting/CI environment.
3. Local credential cache created by vaultlier init (development only).

Entry points

| Import | Surface | Environment | | --------------- | ---------------------------- | ------------------------------------------------------ | | vaultlier | Runtime SDK (createClient) | Edge-safe (Node 18+, Bun, Deno, Workers, Edge, Lambda) | | vaultlier/cli | CLI programmatic API | Node-only |

The runtime entry uses only fetch and Web Crypto - no Node-only imports, no third-party dependencies.

Security

• Secrets are resolved in memory and never written to disk.
• vaultlier.config.json / legacy vaultlier.json and the generated client (lib/vaultlier/vaultlier.ts by default, when enabled) contain metadata only - never secret values or API keys.
• vaultlier audit reports are local files. The config stores only summary metadata: scores, finding titles, severities, paths, detected frameworks, and optional AI recommendations.
• vaultlier audit --ai sends sanitized metadata to the hosted analyzer; it does not upload source files or raw .env values.
• Never commit your VAULTLIER_API_KEY.

License

MIT