CLI reference

Every command, start to finish.

The CLI is a full end-to-end-encrypted client: it generates your keypair, seals your private key, and encrypts every value before it leaves your machine. This page is the complete surface — the Help guides walk you through the workflows.

Getting started guide Contact support

# install, then sign in
$ npm install -g bippass
$ bippass login --server https://your-bippass
$ bippass use acme/api/production
$ bippass run -- npm start
✓ secrets injected · nothing written to disk

Install

The quickest way is npm — it works on macOS, Linux and Windows, and pulls only the binary your machine needs rather than all five.

$ npm install -g bippass
$ bippass --version

The CLI itself is a static Go binary; the npm package is a small launcher that runs it. If you would rather not go through npm, build from source. There is no Homebrew formula yet.

# build into dist/bippass
$ make build


# or install onto your PATH
$ make install

There is no default server, so every command needs to know where your BipPass lives. Pass --server once when you log in and it is saved for you.

Signing in

Logging in does two things: it authenticates you, and it unlocks your encryption key. Your password is used on the spot to re-derive a key that unseals your private key into your OS keyring. It is never stored, and never sent.

bippass login [--email <address>]

Authenticate and unlock your E2EE key.

On a machine you have not used before, login may stop with "Device pending approval" or ask you to verify by email — that is expected, and you re-run login once approved. If your account has TOTP enabled, you are prompted for a code. When you belong to exactly one workspace it is selected as your active context automatically.

--email <address>: Account email. Prompted if omitted.

$ bippass login --server https://your-bippass-server
Email: ada@example.com
Password:
✓ Logged in as ada@example.com · workspace: acme

bippass logout

Clear local credentials — both the token and the unlocked key.

bippass me

Show the current account.

bippass register --server <url>

Create an account directly against a server, generating your keypair locally.

Hidden from --help, because signing up in the browser is the normal path. It still works, and it is the only way to bootstrap an account on a self-hosted server with no web client in front of it. Your password is unrecoverable by design: it seals your private key, and no one — including us — can unseal it for you.

Context & resources

Every secret lives in a workspace, a project, and an environment. Rather than pass all three to every command, you set an active context once. Any part can still be overridden per-command with --workspace, --project, or --env.

bippass use <workspace[/project[/environment]]>

Set the active context.

$ bippass use acme
$ bippass use acme/api/prod

bippass context

Show the active workspace, project, and environment.

bippass workspaces

List the workspaces you can access.

bippass workspaces create <name>

Create a workspace and make it the active context.

bippass projects

List projects in the active workspace.

bippass projects create <name>

Create a project, bootstrapping its encryption key for you.

This generates the project key that seals every secret in the project, and wraps it to your public key. A brand-new project has no environments yet — create one before setting secrets.

bippass environments

List environments in the active project. Aliased to bippass envs.

bippass environments create <name>

Create an environment.

$ bippass projects create api
$ bippass environments create prod
$ bippass use acme/api/prod

Secrets

Values are encrypted on your machine before they are sent, and decrypted on your machine after they come back. The server only ever holds ciphertext it cannot read.

bippass ls [--reveal]

List secrets in the active project and environment.

Values are masked unless you pass --reveal. Every reveal is recorded in the audit log.

--reveal: Decrypt and show values. Each reveal is audited.

bippass get <KEY>

Print one decrypted value to stdout.

bippass set <KEY=VALUE>

Create or update a secret, encrypted locally before it is sent.

$ bippass set DATABASE_URL='postgres://…'
✓ Created DATABASE_URL

bippass delete <KEY>

Delete a secret.

bippass run -- <command> [args...]

Inject secrets as environment variables and run a command.

The safest way to use secrets: nothing is written to disk. The child exits with its own exit code, so this is safe to use as-is in CI.

$ bippass run -- npm start
$ bippass run --env staging -- ./server

bippass pull [--file <path>]

Download and decrypt secrets into a local .env file.

Writes the file with 0600 permissions, and warns you if it is not covered by .gitignore. This puts plaintext on your disk — prefer bippass run where you can.

--file <path>: Output path. Defaults to .env.

bippass push [--file <path>]

Encrypt a local .env file and upload it.

Push only adds and updates. A key you deleted from your .env is not deleted from the server — use bippass sync for that, or bippass delete for one key.

--file <path>: Input path. Defaults to .env.

bippass diff [--file <path>]

Compare a local .env against the server. Read-only.

--file <path>: Local path. Defaults to .env.

bippass sync [--file <path>] [--no-interactive]

Three-way merge a local .env with the server.

Unlike push, sync reconciles in both directions against the last state it saw, so deletions on either side are applied. Where both sides changed the same key it asks you to choose; --no-interactive fails instead, which is what you want in CI.

--file <path>: Local path. Defaults to .env.
--no-interactive: Fail on conflicts instead of prompting.

Team access

Adding someone to a workspace lets them see it exists. It does not let them read anything — decryption needs the project key wrapped to their own public key, which is what grant does.

bippass members

List workspace members.

bippass members add --user-id <uuid> [--role <role>]

Add an existing user to the workspace by user id.

--user-id <uuid>: User id to add. Required.
--role <role>: owner, admin, member (default), or viewer.

bippass grant --email <address> | --user-id <uuid>

Give a member the key to the active project.

This unwraps the project key with your own key and re-wraps it to theirs, so it only works for people who have signed in at least once — until then they have no public key to wrap to. Nothing decryptable passes through the server.

--email <address>: Target member email, resolved among members.
--user-id <uuid>: Target member user id.

$ bippass grant --email dev@acme.com
$ bippass grant --user-id <uuid> --project api

Keeping secrets out of git

The CLI can scan for exposed secrets and install a pre-commit hook that blocks a commit containing them.

bippass scan [--all | --path <path>] [--entropy]

Scan files for exposed secrets. Defaults to staged files.

Matches known key formats — AWS, Stripe, GitHub, Slack, Google, JWTs, private key blocks, and database URLs with credentials. Findings are printed with the secret redacted, and exit is non-zero so a hook or CI job fails.

--all: Scan every tracked file instead of staged ones.
--path <path>: Scan a specific file or directory.
--entropy: Also flag high-entropy strings. Noisier.

bippass hook install

Install the pre-commit secret-scan hook in this repo.

The hook embeds the absolute path to your binary, so it works even when bippass is not on the committer’s PATH, and it chains after an existing pre-commit hook rather than replacing it. Bypass it once with git commit --no-verify.

$ bippass hook install
✓ Pre-commit hook installed → .git/hooks/pre-commit

bippass hook uninstall

Remove the pre-commit hook from this repo.

Global flags

Accepted by every command.

--server <url>: BipPass server URL. Overrides the saved config.
--token <token>: API token. Overrides the config and OS keyring.
--workspace <slug>: Workspace slug. Overrides the active context.
--project <slug>: Project slug. Overrides the active context.
--env <slug>: Environment slug. Overrides the active context.
--output <format>: table (default) or json.
--no-color: Disable coloured output.
-v, --verbose: Debug tracing to stderr: resolved server/context and per-request lines (never the token).

Still stuck?

Talk to a human.

If the reference doesn't cover it, email support@bippass.dev and a real engineer will get back to you. For security disclosures, use security@bippass.dev.