Tools

Command-line tools

passkey-x for the API, agents and self-hosted servers, and pkx for secrets from the desktop app in your scripts.

passkey-x: 0.1.0 · Node.js >=24.7.0
pkx: 1.18.4 · with the desktop app
Output: JSON, ciphertext only

passkey-x

A scriptable view of the ciphertext-only Customer API: workspace, membership, item, sync, mission, request and grant metadata. It never accepts or prints a vault password, recovery key, item plaintext or service-role key. Agent mode (passkey-x agent) is on the Agents page.

Command	What it does
`passkey-x health`	Is the API reachable (GET /v1/health).
`passkey-x item-types`	The item types vault items can have.
`passkey-x workspaces`	The vaults you can open.
`passkey-x members --workspace <uuid>`	Who is in a vault.
`passkey-x items --workspace <uuid>`	The vault's items as encrypted envelopes.
`passkey-x sync --workspace <uuid> [--cursor <sequence>]`	The change feed from a cursor.
`passkey-x missions --workspace <uuid>`	Missions in a vault.
`passkey-x requests --workspace <uuid>`	Access requests in a vault.
`passkey-x grants --workspace <uuid>`	Access grants in a vault.

Example

export PASSKEY_X_ACCESS_TOKEN='<short-lived-user-token>'   # never as an argument
passkey-x workspaces
passkey-x items --workspace <workspace-uuid>
passkey-x sync --workspace <workspace-uuid> --cursor 0

Self-hosted servers

Only connect to a server your organization runs: whoever runs it controls your sign-in. See Self-hosting.

Command	What it does
`passkey-x server set <url>`	Check https://<url>/.well-known/passkey-x.json and use that server (self-hosted).
`passkey-x server show`	Show the server in use.
`passkey-x server reset`	Go back to passkey-x.com.

Environment

Variable	Used by	Meaning
`PASSKEY_X_ACCESS_TOKEN`	passkey-x	Short-lived user access token; never pass it as an argument.
`PASSKEY_X_API_URL`	passkey-x	API base URL; overrides the server (production default is built in). Must start with https://.
`PASSKEY_X_SERVER`	passkey-x, agent	Passkey-X server address, found through /.well-known/passkey-x.json (overrides "server set" for this run).
`PASSKEY_X_CONFIG`	passkey-x	CLI config file (default ~/.config/passkey-x/config.json).
`PASSKEY_X_AGENT_TOKEN`	agent	The agent token from Admin › Sharing & onboarding › Agents (keep it secret).
`PASSKEY_X_AGENT_URL`	agent	Agent API base URL; overrides the server.

pkx

Installed with the Passkey-X desktop app. It takes secrets from the running app after you approve each request there; nothing is written to disk. Turn it on in Settings › This computer › Command-line tool (managed deployments: the commandLine setting).

Command	What it does
`pkx run [--env NAME=px://Vault/Item/field]... [--env-file FILE]... -- <command> [args...]`	Run a command with secrets as environment variables. Variables that already hold a px:// reference (in the shell or an env file) are filled in too.
`pkx read px://Vault/Item/field`	Print one secret.
`pkx help`	Show the usage.
`pkx --version`	Show the version (the desktop app's).

Examples

pkx run --env DATABASE_URL=px://Work/Production DB/password -- npm start
pkx run --env-file .env.passkey -- docker compose up
pkx read "px://Work/GitHub/token"

Secret references

References look like px://<item>/<field> or px://<vault>/<item>/<field>. Fields: password, username, url, notes, totp, a custom field name. Variables in your shell or env file whose value is a px:// reference are filled in as well.

pkx errors

Error	What it means
`denied`	The request was declined in Passkey-X.
`timeout`	No answer from Passkey-X (approve the request in the app).
`locked`	Unlock Passkey-X and try again.
`not_found`	A reference did not match any item or field.
`ambiguous`	A reference matches more than one item; add the vault name: px://Vault/Item/field.
`invalid_reference`	References look like px://Vault/Item/field.
`untrusted_client`	Passkey-X only answers the pkx installed with the app; run that pkx (or a link to it).

Need help building on Passkey-X?

Questions about the API, a bug or a missing endpoint? Our team replies by email, usually within one business day.

Contact developer support Help Center