Skip to main content
Run promptster with no arguments to open an interactive menu, or pass a command directly:
The commands you’ll use in a normal assessment are start, brief, explain, and done. The rest are for checking status or recovering from a problem.

​
Core commands

Redeems your key, sets up your workspace, configures your editor, and starts the session. This is the first command you run.
What start does:
1

Redeems your key & accepts terms

Validates the key, then walks you through the data-capture notice and the optional authorship-timing question.
2

Prepares your workspace

Uses your current folder, a path you choose, or a fresh ~/promptster-test. If the assessment includes a starter repo, it’s cloned at the correct commit.
3

Chooses your AI tool

Prompts you to pick Claude Code, Codex, or Cursor (or configures all of them). Skip the prompt with --tools. The CLI only checks for the tool(s) you pick.
4

Writes TASK.md

Saves the task brief to TASK.md and adds .promptster/ to .gitignore.
5

Configures hooks & AI access

Writes hooks for your chosen tool into your workspace. In the default managed mode it also routes the AI through the Promptster proxy, so you don’t sign in to the model yourself. If the assessment uses your own subscription, you sign in to your tool normally and capture happens through its transcript — see how the AI is set up.
6

Smoke-tests capture

Fires one tiny request (managed mode) so any auth or network problem surfaces now, not on your first prompt.
Flags:
After start, open your AI tool (Claude Code, Codex, or Cursor) from the workspace directory in a new window. Hooks are scoped to that folder — a tool that was already open won’t capture your session. Use --restart (or restart your tool yourself) if it was already running.
Captures the why behind a choice. Three ways to use it:
Inside Claude Code you can also use the /explain slash command, which calls this under the hood. The CLI shows a summary of your recent activity for context, then records your note as part of your session.See Decisions for the full workflow.
Opens the structured task brief — scenario, codebase orientation, phases, evaluation dimensions, and ground rules — with a live countdown, in a new terminal window so it stays visible beside your editor.
The same brief also lives in TASK.md in your workspace. The assessment title and the nature of the planted defect are deliberately omitted so they can’t leak hints about the solution.
Bundles and uploads your workspace, flushes remaining events, and marks the session complete.
On success you get a results link (copied to your clipboard), and your hooks, shell hook, and (in managed mode) proxy config are cleaned up automatically. The workspace is then safe to delete.
If you started decision notes that are still empty, done refuses to proceed until you finish them with promptster explain (or pass --auto). If the upload fails, done exits with an error rather than falsely reporting success — re-run it once your connection is back.

​
Status & diagnostics

Session ID, start time, elapsed time, time remaining (if a limit is set), and the live event count the server has received.
Use the event count to confirm capture is working — it should climb as you prompt and edit. If it’s stuck at zero, see Troubleshooting.
Runs a full health check and prints each result with ✓ (pass) or ✗ (fail) plus a suggested fix. It checks:
  • git and the binary for each AI tool your session uses (claude, codex, or cursor) are on your PATH
  • the promptster binary is installed and ~/.promptster/bin is on your PATH
  • no conflicting ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN is exported in your shell (these break the managed proxy)
  • your session is active and not expired, and (in managed mode) a token can be resolved
  • your tool’s hooks and, in managed mode, the proxy config are present in your workspace
  • the shell hook is installed and sourced
  • the API is reachable and your session is fetchable
Run this first whenever something seems off.
Confirms that the events recorded for your session are cryptographically signed and form an unbroken chain.
Output is either ✓ N / N events signed · chain intact or a clear failure. Sessions started with an older CLI may be unsigned, which the command reports plainly.
Prints the installed CLI version.

​
Recovery

Tears down the current session, hooks, shell hook, and proxy config without submitting any code or completing the assessment.
Use this if you want to walk away from a session cleanly. It does not flip your key’s status, so reach out to the hiring team if you intended to submit.
Like abort, but also sweeps leftover global config under ~/.promptster. It resolves your workspace even when the session file is corrupt, so it works when nothing else does.
See Recovering from a broken setup.
Emits shell unset lines for ANTHROPIC_* variables left behind by an older session. Run it if doctor reports a conflicting export:
(Bare promptster env is an internal session-expiry check — it prints nothing.)

​
How the AI is set up

Every assessment runs in one of two modes. You don’t choose it — the assessment does, and start configures the right one automatically. If an assessment uses your own subscription, start sets --byo-subscription for you (you rarely pass it by hand). In this mode there’s no proxy to smoke-test or clean up, and doctor won’t check for proxy config. Everything else — hooks, explain, done — works the same.

​
Advanced & internal commands

You’ll almost never run these directly, but they exist:
  • promptster redeem <key> — validates a key and accepts the terms without cloning a repo or installing hooks. start does this for you; use redeem only if the hiring team asks you to.
  • promptster auth-token — prints a session auth token for tooling. Internal; not needed in a normal assessment.

​
Interactive menu

Running promptster with no arguments opens a numbered menu. Type a number, or paste your PST-XXXX-XXXX key directly — the CLI detects the prefix and routes to start.