CLI commands

Run any command with --help for the same information in the terminal.

Project setup

`valetkey init`

Sets up valetkey in the current project: creates your machine identity, the recipients file, an empty vault, a starter valetkey.config.ts, and a .gitignore entry for playwright/.auth/. Fails if a config already exists.

Option	Effect
`--name <name>`	App name (defaults to the directory name)
`--origin <origin>`	Dev origin (defaults to `http://localhost:3000`)
`-y, --yes`	Accept defaults without prompting

`valetkey doctor`

Checks the config loads, an identity exists, this machine is a vault recipient, and the vault decrypts. Exits non-zero if anything fails.

Sessions

`valetkey login <persona>`

Mints a session for the persona via your provider and saves the artifact. If the managed browser is already running, the session is injected into it.

Option	Effect
`--export <path>`	Also write a Playwright storage-state file to this path
`--browser`	Start the managed Chrome profile if it is not running, then inject
`--no-browser`	Never touch the browser; just mint and save

`valetkey export <persona> --out <path>`

Writes an existing, unexpired session as a storage-state file. Errors if there is no active session; run login first.

`valetkey logout [persona]`

Revokes the persona’s session (calling the provider’s revoke if it has one), deletes the artifact, and clears the session from the managed browser if it is running. Without an argument, signs out every persona.

`valetkey list`

Shows each configured persona with its session status: active until when, expired, or no session.

`valetkey seed [persona]`

Runs the provider’s seed to provision the persona’s user in your auth system. Without an argument, seeds every persona.

Browser and agents

`valetkey browser`

Launches the managed Chrome profile for this app, or reports the one already running. See the managed browser.

Option	Effect
`--print-devtools-config`	Print MCP config for Chrome DevTools MCP and Playwright MCP with the current port
`--stop`	Forget the running browser so the next launch is fresh

`valetkey state`

Prints the managed browser’s port, process id, start time, and profile path, or says nothing is running.

`valetkey mcp`

Runs the MCP server on stdio for coding agents. Not meant to be run by hand; register it in your agent’s MCP config. See the MCP tools reference.

Vault and team

`valetkey vault set <key>`

Stores a secret. The value is prompted interactively or read from stdin when piped, never taken as an argument. Refuses values matching live key patterns.

`valetkey vault rm <key>`

Removes a secret and re-encrypts the vault.

`valetkey vault list`

Prints secret names. Values are never shown by any command.

`valetkey team add <name> <recipient>`

Adds a teammate’s age public key and re-encrypts the vault to all recipients.

`valetkey team rm <nameOrKey>`

Removes a recipient and re-encrypts. Rotate the affected secrets afterwards; the removed person may have copies of the old vault.

`valetkey team list`

Prints all recipients with their names.

`valetkey identity create`

Creates this machine’s keypair in the OS keychain (file fallback at ~/.valetkey/identity on headless machines). Reports the existing identity if one is already there.

`valetkey identity show`

Prints this machine’s public key. Safe to share; teammates need it for team add.

Observability

`valetkey audit`

Shows recent audit events (mints, exports, seeds, revocations) as JSON lines, secrets redacted.

Option	Effect
`--tail <count>`	Number of events to show (default 20)

Environment variables

Variable	Effect
`VALETKEY_HOME`	Where machine-local state lives. Defaults to `~/.valetkey`. Useful for CI.
`VALETKEY_CHROME_PATH`	Path to the Chrome executable, for non-standard installs
`VALETKEY_DEBUG`	Set to `1` to trace browser work on stderr