CLI Reference

Create zero-knowledge self-destructing notes from your terminal, scripts, Dockerfiles, and CI pipelines.

Installation

macOS · Linux (via Homebrew)

brew tap quantum-encoding/tap && brew install voidnote

Any platform with Go installed — the binary is named voidnote-cli

go install github.com/quantum-encoding/voidnote-cli@latest

Pre-built binaries for macOS, Linux (amd64/arm64), and Windows are available on the releases page.

Authentication

voidnote read needs no account. voidnote send and voidnote stream create use an API key from a free account — create one, then generate a key on your dashboard. Log in once and the CLI stores credentials in ~/.config/voidnote/credentials.

shell

# interactive login
voidnote login

# non-interactive (CI)
VOIDNOTE_TOKEN=<api-token> voidnote send ...

voidnote send

Encrypt content and return a share link. Content is never sent in plaintext.

usage

voidnote send [flags]

examples

# pipe stdin

echo "deploy key: abc123" | voidnote send

# 3 views, expires in 6 hours

voidnote send --views 3 --expires 6h

# send a file

voidnote send < secrets.env

# output just the URL (useful for scripting)

voidnote send --quiet < secret.txt

Flag	Default	Description
--views	1	Max views before destruction (1–100)
--expires	24h	Expiry: 1h, 6h, 24h, 3d, 7d, 30d
--api-key	—	API key (overrides `VOIDNOTE_API_KEY` env / stored credentials)
--quiet	false	Print only the URL, no decoration
--json	false	Output result as JSON `{"url","token","expiresAt"}`

voidnote read

Fetch and decrypt a note by URL. Counts as one view.

examples

# print to stdout — paste the full URL including #key

voidnote read "https://voidnote.net/n/<token>#<key>"

# save to file

voidnote read <url> --out secrets.env

# pipe into a command

voidnote read <url> | source /dev/stdin

voidnote stream

Live encrypted channels — pipe any output through an ephemeral encrypted channel using just a URL. The channel is destroyed when it is closed or its lifetime runs out.

Command	Description
voidnote stream create	Create a stream and print its URL. `--ttl` 3600, 21600 or 86400 seconds; `--title` optional
voidnote stream write <url>	Send stdin to the stream — one message per line when stdin is piped
voidnote stream watch <url>	Print messages as they arrive. `--raw` for plain text, `--json` for one JSON object per message
voidnote stream close <url>	Close the stream and destroy its content

Other commands

Command	Description
voidnote login	Authenticate and store credentials
voidnote logout	Remove stored credentials
voidnote status	Show who you're logged in as
voidnote list	List your recent notes (title, expiry, views remaining)
voidnote version	Print CLI version

CI / CD examples

GitHub Actions — send secrets to a teammate without storing them in logs:

.github/workflows/share-creds.yml

- name: Share deploy key
  run: |
    echo "${{ secrets.DEPLOY_KEY }}" \
      | voidnote send --views 1 --expires 1h --quiet
  env:
    VOIDNOTE_API_KEY: ${{ secrets.VOIDNOTE_API_KEY }}

Dockerfile — read the secret when the container starts, without baking it into the image:

Dockerfile

# voidnote installed in the image (see Installation above).
# The note is read when the container starts, never in a RUN step,
# so the secret is not written into an image layer.
# docker run -e VOID_URL="https://voidnote.net/n/<token>#<key>" image
ENTRYPOINT ["sh", "-c", "voidnote read \"$VOID_URL\" > /tmp/app.env && exec \"$@\"", "--"]
CMD ["/app"]

Environment variables

Variable	Description
VOIDNOTE_API_KEY	API key — overrides stored credentials (use in CI)
VOIDNOTE_TOKEN	Same as `VOIDNOTE_API_KEY`, used when that is unset

HTTP API reference → GitHub: quantum-encoding/voidnote-cli → Release binaries → version.json — machine-readable version info →