Skip to content

For the complete documentation index, see llms.txt.

Promptless Promptless | Automatic updates for your customer-facing docs
Get a demo Start for free

Developer quickstart

This page is for engineers working on the Promptless CLI itself — or for coding agents asked to verify that a build of the CLI behaves correctly against its documented contracts.

The CLI ships with a promptless-test-fixture helper that stands in for both the web app and the API. It binds a fake server to 127.0.0.1 on a random port, pre-allocates a deterministic test API key, and serves the two endpoints the CLI cares about (GET /cli/auth and GET /v1/me). Every assertion below is exercised against that fixture — no real Clerk account, no real Promptless backend.

Prerequisites

Section titled “Prerequisites”
  • A built promptless binary on $PATH.
  • The promptless-test-fixture helper from the same build on $PATH.
  • curl (used by the test specs to drive the auth flow without a GUI browser).

Smoke test:

Terminal window
promptless --help | head -1
promptless-test-fixture --help | head -1

If either fails, fix the install before running the specs below.

Test specs

Section titled “Test specs”

Each spec is a self-contained, agent-runnable document. Hand one to a coding agent and ask it to execute the phases top-to-bottom, recording PASS / FAIL for every Assert line. Specs share the same fake-server fixture; the contract for that fixture is defined in the happy-path spec and referenced by the others.

  • Test spec: authentication happy path — the end-to-end login → whoami → logout flow. Also the canonical definition of the promptless-test-fixture contract.
  • Test spec: config file paths — resolution order across $PROMPTLESS_CLI_DEVELOPER_CONFIG_FILE, $XDG_CONFIG_HOME, and the ~/.config default, plus file/directory permissions.
  • Test spec: env-var precedence — how $PROMPTLESS_CLI_API_SECRET in the environment overrides the cached config file, including the “bogus env beats valid file” case.
  • Test spec: logout edge cases — preserving unrelated keys, deleting empty files, idempotency, and the warning emitted when the env var is still set after logout.

Suggested order

Section titled “Suggested order”

Run them in the order above. The happy path is the broadest coverage and shakes out fixture / installation problems before the more focused specs assume a working baseline. The other three are independent of each other and can be parallelized once the happy path passes.

Section titled “Related reading”
  • Configuration — the user-facing version of what the path-resolution and env-var specs are testing.
  • Environment variables — full reference for every variable the CLI reads.
  • CLI auth protocol — the wire-level contract the fixture implements on the server side, including the v1 RSA-OAEP key delivery format.