Configuration

The Promptless CLI stores its state in a single file: an env-style file that contains the cached API key created by promptless login. Everything else is either read from process environment variables (see Environment variables) or passed as command-line flags.

Config file location

The path is resolved at runtime, in this order:

Priority	Source	Resolved path
1	`$PROMPTLESS_CLI_DEVELOPER_CONFIG_FILE`	the literal value of the env var
2	`$XDG_CONFIG_HOME`	`$XDG_CONFIG_HOME/promptless/env`
3	default	`~/.config/promptless/env`

The first source whose env var is non-empty wins. If $XDG_CONFIG_HOME is unset or empty, the CLI falls through to the default — it does not invent a fallback like /etc/xdg.

When to use the developer override

PROMPTLESS_CLI_DEVELOPER_CONFIG_FILE exists for tests and for running multiple Promptless identities on the same workstation (one per shell). Setting it to a path under /tmp/ is a common pattern:

export PROMPTLESS_CLI_DEVELOPER_CONFIG_FILE=/tmp/promptless-staging.env
promptless login    # writes to /tmp/promptless-staging.env
promptless whoami   # reads from /tmp/promptless-staging.env

A new shell without the env var will go back to reading the default file — identities are scoped to the shell that set the override.

File format

The file is a minimal KEY=VALUE env file. One assignment per line. Blank lines and lines starting with # are ignored. Surrounding single or double quotes around the value are stripped on read.

PROMPTLESS_CLI_API_SECRET=plk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The CLI only writes one key — PROMPTLESS_CLI_API_SECRET — but if you add additional KEY=VALUE lines by hand they are preserved across login and logout runs. logout only removes the PROMPTLESS_CLI_API_SECRET line; other keys stay put.

If the file ends up empty after logout, the file itself is deleted rather than left as a zero-byte artifact.

File permissions

promptless login creates the file with mode 0600 (rw-------) and its parent directory with mode 0700. These modes are re-applied on every write, so a chmod 644 you ran by mistake will be reverted on the next login.

The file contains a bearer token for the Promptless API. Anyone who can read it can impersonate this CLI session until the key is revoked from the web app, so do not loosen the permissions and do not commit the file to source control.

How the config file interacts with environment variables

For the single value the CLI cares about — the API secret — the resolution order is:

$PROMPTLESS_CLI_API_SECRET from the process environment, if set and non-empty.
PROMPTLESS_CLI_API_SECRET parsed out of the config file.

The env var always wins. This is what lets you run a one-off command as a different user without overwriting the cached file:

PROMPTLESS_CLI_API_SECRET=plk_other_user promptless whoami

The same name appears in both places on purpose: anything you export in your shell behaves the same as anything written to the config file. The config file is just a way to make the export persistent across sessions.

Inspecting and removing the config

There is no promptless config command. To inspect the file directly:

cat "${PROMPTLESS_CLI_DEVELOPER_CONFIG_FILE:-${XDG_CONFIG_HOME:-$HOME/.config}/promptless/env}"

To remove it, prefer promptless logout over rm — it handles the empty- file case and warns you if $PROMPTLESS_CLI_API_SECRET is still set in the current shell (which would mask the deletion).

Server endpoints

The CLI talks to two services:

App (https://app.gopromptless.ai by default) — only used by promptless login to redirect the browser through Clerk.
API (https://api.gopromptless.ai by default) — used by every command that authenticates with the cached API key.

Both can be overridden with environment variables for staging or local development; see Environment variables.