CLI

Follow the complete prompt lifecycle walkthrough after installation to create, evaluate, compare, and publish a ticket router.

The CLI runs on your local development computer. Its standalone binary includes its runtime; Node.js and Bun are not required to run the downloaded executable.

Install and update

Use the installer for your platform:

curl -fsS https://www.promptlens.io/install.sh -o install-promptlens.sh
sh install-promptlens.sh

Invoke-WebRequest https://www.promptlens.io/install.ps1 -OutFile install-promptlens.ps1
./install-promptlens.ps1

Installers verify SHA-256 checksums and install into your user account. Add the printed install directory to PATH if needed. promptlens upgrade explicitly installs the latest release; promptlens upgrade --to VERSION chooses a particular version. Profiles remain separate from the executable. Choose a release asset matching your operating system and architecture.

Sign in

promptlens login
promptlens organizations list
promptlens organizations use --org org_example
promptlens status

Login opens your browser for Clerk sign-in and explicit consent. The CLI uses PKCE and a temporary loopback callback. It does not contain a client secret. Use --no-browser to open the displayed sign-in URL manually on the same computer.

Credentials use your OS secure credential store by default: macOS Keychain, Linux Secret Service, or Windows Credential Manager. Unlock or enable the store if login cannot save credentials. Storage never changes automatically.

If your environment has no usable secure store, explicitly opt in to a private plaintext file:

promptlens login --credential-store file

The warning is intentional: file permissions restrict access to your OS account, but the credentials are not encrypted by the CLI.

Profiles and organizations

Use --profile NAME to keep separate logins and settings. Each profile has its own local organization context; an explicit --org overrides it for one command. Changing an account default does not silently retarget an existing profile. An inaccessible organization requires choosing another organization explicitly.

For a development deployment, pass its public origin:

promptlens login --profile development --api-url https://your-development-origin.example

Local HTTP origins are allowed for development. Use HTTPS for remote deployments.

Local coding agents

A local agent can invoke the CLI using your signed-in profile and OS account. --json writes a stable result or error to stdout; progress and diagnostics go to stderr. A nonzero exit code indicates failure.

promptlens organizations list --json
promptlens organizations list --all --json

A list returns one page by default. Use --cursor to continue or --all to collect every page. Use JSON files for structured input and --file - to read JSON from stdin.

Destructive or billable commands require confirmation. Local agents and scripts must receive your authorization and pass --yes for that invocation. Noninteractive execution without confirmation fails before performing the operation. The flag does not bypass permissions, revisions, or browser handoffs.

Disconnect

promptlens logout

Logout revokes this connection before deleting its local credentials. If revocation fails, credentials remain so you can retry. Other installations stay connected. Accepted evaluations keep running.

If local credentials are missing or corrupt, run promptlens logout --local-only before signing in again. This clears local settings without claiming remote revocation; an old grant may remain active.

Evaluations and safe retries

promptlens evals start --prompt-id PROMPT_ID --version-id VERSION_ID --scoring-method expected --yes --wait --json

Without --wait, evaluation start returns accepted IDs immediately. With it, the CLI observes both comparison sides and preserves their IDs in success and error output. Ctrl+C stops waiting and returns exit code 130; it does not cancel accepted work. Use the explicit cancel command when you intend to cancel.

Reuse the request key printed on stderr with --idempotency-key when retrying an uncertain write. A lost retrieval-key creation response returns secret_unavailable with nonsecret key metadata; explicitly revoke that key and create another with a new request key to recover. The CLI never silently creates a replacement key.

Command groups and output

Use promptlens --help to list command groups and append --help to a command for its exact flags. Common groups include prompts, draft, dataset, versions, labels, evals, keys, members, providers, and billing. Structured bodies use JSON files; ordinary property flags use kebab case, such as --draft-revision.

JSON success output uses { "data": ... }, while errors use { "error": ... }. Use the exit code before parsing a success field. In scripts, preserve the returned prompt, version, and evaluation IDs rather than locating targets only by name.

An evaluation error or timeout can still include accepted run IDs. Keep those IDs and inspect the existing work before starting another run. See cancel, retry, and review and troubleshooting.