@nsec/cli

Zero-Knowledge Secret Vault, Web Admin Dashboard & Runtime Process Injector

Quickstart • Command Reference • Offline Caching • Security Model

Overview

@nsec/cli (nsec) is the command-line interface for NullSec (zVault), a zero-knowledge secrets management platform.

Unlike legacy secret managers that dump plaintext .env files onto developer disk or inject heavy vendor SDKs into your application code, @nsec/cli operates on a zero production dependency model:

• Decrypts project secrets in client memory using your local OS Keyring keys.
• Directly injects decrypted secrets into the spawned process (process.env).
• Never writes unencrypted secrets or private keys to disk.
• Retains full functionality offline via encrypted local ciphertext caching.

Installation

# Global installation
npm install -g @nsec/cli
# or with pnpm
pnpm add -g @nsec/cli

# Or run directly with npx
npx @nsec/cli --help

The CLI registers three interchangeable aliases: nsec, nullsec, and zvault.

Quickstart

1. Register Local Identity

Generate your Ed25519 signing keypair and RSA-4096 encryption keypair, save private keys in your OS Keyring, and register public keys on the server:

# First user automatically becomes the server administrator
nsec register [email protected] --server http://localhost:4000

# Subsequent users register with a single-use invite token
nsec register [email protected] --token ns_inv_xxx --server http://localhost:4000

2. Initialize a Project

Initialize NullSec in your repository root. Generates an encrypted Project Master Key and writes nullsec.config.json:

nsec init -p my-awesome-app

3. Add and Retrieve Secrets

# Set secrets in development environment
nsec set DATABASE_URL "postgres://postgres:secret@localhost:5432/mydb"
nsec set STRIPE_SECRET_KEY "sk_test_51Mz..."

# Set secrets in production environment
nsec set DATABASE_URL "postgres://prod-db:5432/mydb" -e production

# View secrets in client memory
nsec get
nsec get DATABASE_URL

4. Run Application with Injected Secrets

Execute any application process with secrets securely populated into process.env in RAM:

# Development (default)
nsec run -- npm run dev

# Specific environment
nsec run -e production -- node server.js

Command Reference

| Command | Description | |---|---| | nsec register <email> | Generate cryptographic identity keypair and register on server | | nsec init [-p project] | Initialize project configuration (nullsec.config.json) | | nsec set <KEY> <VALUE> | Encrypt and store an environment variable | | nsec get [KEY] | Decrypt and inspect environment variables in memory | | nsec run [-e env] -- <cmd> | Spawn child process with decrypted secrets injected into process.env | | nsec migrate <file> | Ingest existing .env file, encrypt to server, and redact plaintext | | nsec dashboard | Open Zero-Knowledge Web Admin Dashboard with cryptographic signature ticket | | nsec member add <email> | Grant project access and share envelope keys with a team member | | nsec token [-e env] --name <n> | Generate CI/CD service token (zv_st_...) with zero-knowledge envelope | | nsec rotate-keys | Cryptographically rotate local keypair without project lockouts | | nsec whoami | Inspect active local identity and registered server keys | | nsec admin users | (Admin) List all registered users on the server | | nsec admin promote <email> | (Admin) Promote a server member to administrator | | nsec invite <email> | (Admin) Generate single-use signed invite token |

Offline Caching

nsec run includes an encrypted local fallback caching engine:

• When online, fetched ciphertext is cached at ~/.nullsec/cache/<server>/<project>/<env>.json.
• If the server or network becomes unreachable, nsec run automatically falls back to cached ciphertext and decrypts it with your local private key.
• Sensitive values are never cached in plaintext.
• Use --no-cache to bypass or --offline to enforce offline mode.

CI/CD Automation

Generate a service token for automated runner environments (e.g. GitHub Actions):

nsec token -e production --name "GitHub-Actions"
# Output: zv_st_tok_...

In your CI environment:

export NSEC_TOKEN="zv_st_tok_..."
nsec run -e production -- npm run build

License

MIT © NullSec / zVault Contributors