Guides

Guide 1

Inject secrets into a program (no .env on disk)

pock run decrypts a folder's secrets and starts your command with those values as environment variables. Pock does not write the plaintext to a .env file.

pock login
pock vault set app DATABASE_URL=postgres://… STRIPE_KEY=sk_live_…

pock run -p app -- npm start
# or: pock run -p app -- node server.js
# or: pock run -p app -- ./deploy.sh

Your shell expands $VARS before Pock runs. Print a value from the child process:

pock run -p app -- printenv DATABASE_URL
pock run -p app -- sh -c 'echo "$DATABASE_URL"'

Guide 2

Use Pock in GitHub Actions (scoped machine key)

Give the CI job a machine key that can decrypt one subtree. A compromised runner exposes the secrets that were granted to that key.

1. Put the job's secrets under one folder, then create a scoped key and write it directly to the repository's GitHub Actions secrets. The Pock CLI passes each value to gh over standard input without printing it or using the clipboard:

pock vault set acme.web.prod DATABASE_URL=… STRIPE_KEY=…
pock vault machine create acme.web.prod --github <owner>/<repo>
# ✓ writes POCK_MACHINE_KEY + POCK_TOKEN to the repo's GitHub secrets

(Omit --github to print the values and add them by hand.) 2. Use them in the workflow:

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      POCK_TOKEN: ${{ secrets.POCK_TOKEN }}
      POCK_MACHINE_KEY: ${{ secrets.POCK_MACHINE_KEY }}
    steps:
      - run: curl -fsSL https://pock.sh/install | sh && echo "$HOME/.pock/bin" >> "$GITHUB_PATH"
      - run: pock run -p acme.web.prod -- npm run deploy

CI uses the machine key and token, with no interactive login. After adding secrets under the scope, re-run pock vault machine create acme.web.prod to include them. List with pock vault machine ls, revoke with pock vault machine rm <id>.

Guide 3

Set up Pock on a new machine

Pock stores your vault ciphertext on the service. To use it on another laptop or server, link that device once with your passphrase and Secret Key.

curl -fsSL https://pock.sh/install | sh
pock login
pock vault link          # enter your Secret Key + passphrase once

After linking, the local vault file holds the Secret Key and your passphrase opens the vault. Commands such as pock run and vault get can then decrypt values. On the web, "Set up this device" performs the equivalent setup.

Guide 4

Import a .env, then export or run with it

Import an existing .env, then export it as a file or supply its values to a process. The import creates secret items and a reusable environment, a named view that preserves the exported variable names.

pock vault import .env --env prod          # creates secrets + a 'prod' environment
pock run -e prod -- npm start              # inject the environment's secrets
pock vault env export prod --file .env     # write it back out as a .env

-p <folder> injects a folder's secrets (item names = var names). -e <environment> injects an environment's secrets (export keys = var names).

Guide 5

Other CI / non-interactive (the env-var reference)

Any pipeline can drive Pock with environment variables. Supply one authentication variable and one decryption option:

# Auth (pick one)
POCK_TOKEN=…          # a bearer token from 'pock token' (skips 'pock login')

# Decryption (pick one)
POCK_MACHINE_KEY=…    # a scoped machine key (best for CI - decrypts one subtree)
POCK_SECRET_KEY=…     # your account Secret Key (full vault access)
POCK_PASSPHRASE=…     # your passphrase (with a local vault.json, or with POCK_SECRET_KEY)

# Optional
POCK_BASE=https://www.pock.sh   # override the server

export POCK_TOKEN="$POCK_TOKEN" POCK_MACHINE_KEY="$POCK_MACHINE_KEY"
pock run -p acme.web.prod -- ./release.sh

Guide 6

Reset a forgotten passphrase

Your recovery code, saved during setup, can open the vault and let you set a new passphrase. On the web, choose "Forgot your passphrase? Use your recovery code." Enter the code, then set a new passphrase if this device has your Secret Key.

Guide 7

Back up your vault to a file

Open your account menu → Vault → Encrypted backup and choose a backup passphrase. Pock decrypts the readable secrets, seals them into a single .pockvault file, and downloads it. Store that file wherever you keep important backups.

To restore, come back to the same panel, pick the file, enter its passphrase, and Pock decrypts it locally so you can preview and re-import the secrets.

Guide 8

Rotate your keys

From your account menu → Vault → Rotate your keys you can change any factor without wiping the vault:

Change passphrase, rotate Secret Key, and rotate recovery code replace the corresponding wrap around your account key. Secret items are not re-encrypted. A new Secret Key or recovery code is shown once; save it before closing.

Use rotate identity keys after a suspected compromise. It creates a new keypair and re-encrypts every readable personal secret to that key. Open protected namespaces first. Item history and trash are cleared because those blobs use the old key; team secrets require separate re-keying by a team admin.