Skip to main content
This is the happy path from email to submission. If anything misbehaves along the way, Troubleshooting has a fix for every common snag — and promptster doctor will diagnose your setup at any point.
1

Install the CLI

The script downloads a single binary to ~/.promptster/bin/promptster and adds it to your shell profile. Restart your shell (or run the export PATH=... line the installer prints) so promptster is on your PATH.Prefer npm? npm install -g @promptster/cli works too. See Install for details and verification.
2

Start your assessment

Run promptster start with the key from your invitation email:
start validates the key, shows your assessment details (organization and time limit), and walks you through setup. The assessment title is intentionally hidden — the task brief is the single source of truth for what you’re asked to do.
3

Review and accept the data notice

The CLI shows exactly what is and isn’t captured, then asks you to type yes to accept the terms of service.Captured during your session:Never captured: keystrokes, screen recordings, your clipboard, environment variables/secrets, or anything outside the workspace.You’ll then be asked one optional question — whether to allow cadence-based authorship checks (timing between your prompts and commands, to help reviewers distinguish typed work from pasted work). You can answer no and still take the assessment normally. See Privacy & Data.
4

Choose your AI tool and workspace

start asks which AI tool you’ll use — Claude Code, Codex, or Cursor — and where to work. You can use the current folder, enter a custom path, or let it create a fresh ~/promptster-test directory. If the assessment ships a starter repo, the CLI clones it at the correct commit for you.It then writes your task to TASK.md and configures your tool’s hooks. 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’ll sign in to your tool as usual. When setup finishes you’ll see your task brief and the workspace path.
5

Open your tool from the workspace — then build

Open your AI tool (Claude Code, Codex, or Cursor) from inside the workspace directory, in a new window. Hooks and the AI proxy are scoped to that folder — a window that was already open, or one started from a different directory, will not be captured.
Now work normally. In the default managed mode you don’t need to sign in to the model at all — Promptster routes it through the proxy for the assessment. If the assessment uses your own subscription, just sign in to your tool as you normally would. Check your task or time remaining anytime:
6

Explain your key decisions

When you make a meaningful choice — picking an approach, a data structure, a tradeoff — record why in your own words. Inside Claude Code, use the slash command:
Or from any terminal in the workspace:
This is one of the most valuable parts of your submission. The CLI will also nudge you after a chunk of work if you haven’t explained anything recently. See Decisions.
7

Submit when done

This bundles and uploads your workspace, flushes remaining events, marks the session complete, and prints a link to your own session replay (it’s copied to your clipboard). If you started decision notes but left them empty, done asks you to finish them first — or run promptster done --auto to skip that check.Once submitted, the workspace is safe to delete and the hiring team is notified automatically.
Your session data is retained for 30 days. To request deletion or a copy of your data, see Privacy & Data.