Skip to main content
Run promptster with no arguments to open an interactive menu. Pass a command directly to skip the menu. 
promptster <command> [flags]

​
Command reference

Redeems your assessment key, clones or prepares your workspace, configures Claude Code and Cursor hooks, and starts the session. This is the first command you run.
promptster start PST-ABCD-1234
The key format is PST-XXXX-XXXX. You can also run promptster with no arguments to get an interactive menu that prompts you for the key.What start does:
1

Redeems your key

Validates the key against the Promptster API and loads the session.
2

Accepts terms of service

Prompts you to review and accept before proceeding.
3

Prepares your workspace

Clones the starter repo (if provided) or lets you choose a workspace directory.
4

Configures hooks

Writes Promptster hooks into your Claude Code and Cursor project settings so telemetry is captured automatically.
5

Saves your session

Saves your session state locally and starts background event monitoring.
Flags:
FlagDescription
--accept-tosAccept the terms of service non-interactively (for scripted or CI use).
--workspace PATHUse PATH as the workspace directory instead of prompting interactively.
Example — non-interactive:
promptster start PST-ABCD-1234 --accept-tos --workspace ~/my-assessment
The task brief is also written to TASK.md in your workspace so Claude Code and Cursor can reference it directly.
Submits your assessment. Uploads workspace code, flushes all buffered events, and marks the session complete.
promptster done
When submission succeeds, you receive a results link. The session state and hooks are cleaned up automatically.
If you have queued decision items that still need rationale, promptster done will refuse to proceed. Run promptster explain to document them first.
Shows the current task brief, time remaining, and workspace path. Use this to check the task description at any point during your assessment.
promptster brief
Alias: promptster taskThe same information is also available in TASK.md in your workspace root.
Shows session info: session ID, start time, time elapsed, time remaining (if a limit is set), and the live event count fetched from the backend.
promptster status
Example output:
╭──────────────────────────────────────────────────────────────╮
│ Assessment Status                                            │
│                                                              │
│ Session ID:  sess_01abc...                                   │
│ Started:     2025-01-15 09:30:00                             │
│ Elapsed:     42m15s                                          │
│ Remaining:   17m45s                                          │
│ Events:      134                                             │
│ Status:      active                                          │
╰──────────────────────────────────────────────────────────────╯
Opens an interactive terminal UI to document your decision rationale for recent work. Use this to capture the why behind significant architectural choices.
promptster explain
promptster explain --last 30m
Flags:
FlagDefaultDescription
--last <duration>20mHow far back to look for recent activity (e.g. 15m, 30m, 1h). Max 60 minutes.
When you run promptster explain, the CLI:
  1. Fetches a summary of your recent activity (files changed, commands run) from the backend.
  2. Displays the activity context in a box.
  3. Opens a multi-line text editor — type your rationale, then press Ctrl+D to submit or Esc to cancel.
You can also pass rationale directly as an argument for quick one-liners:
promptster explain "chose Postgres over SQLite because the task requires concurrent writes"
See Decisions for more detail on how decision capture works.
Checks your local Promptster setup and reports the status of each component: CLI version, active session, Claude Code binary, project hooks, and PATH configuration.
promptster doctor
Each check is printed with a green ✓ (pass) or red ✗ (fail). Failed checks include a suggested fix command.Run this first if hooks don’t appear to be capturing events, or if promptster start behaves unexpectedly.
Prints the installed CLI version.
promptster version

​
Interactive menu

Running promptster with no arguments opens a numbered menu. You can type a menu number or paste your assessment key directly at the prompt — the CLI detects the PST- prefix automatically. 
  Promptster  v1.2.3

   1  Start assessment       Redeem a key and begin
   2  View task brief        Show the current task + time remaining
   3  Explain a decision     Document your rationale for recent work
   4  Check status           Show session info and event count
   5  Submit assessment      Push code and complete the session
   6  Help                   Show all available commands

  ❯