TalentPrism CLI

The TalentPrism CLI (tp) is an API-backed command-line interface for people and shell-capable AI agents. It gives stable JSON output, structured errors, team-scoped access, recruiter-assistant workflows, and draft sequence creation without browser automation. Every change it makes to TalentPrism data goes through a preview and a one-time approval token first.

Agent-readable command reference

Use tp when an agent needs to inspect TalentPrism sequences, candidates, interviews, reminders, campaign summaries, activity summaries, metrics, copilot briefs, or evidence about a candidate or a lead, or when it needs to make a change through the same Django-backed permissions and validation used by the web app.

Install

Install the CLI with a Python tool installer (Python 3.11 or newer):

pipx install talentprism-cli
uv tool install talentprism-cli

Check the installed version:

tp --version

For local development from the fleetapp repository:

python -m pip install -e .

Sign in

The default server is https://talentprism.ai. Set TALENTPRISM_BASE_URL (or pass --base-url) only for local development or staging.

People: tp login

Run:

tp login

tp login opens your browser. You pick a team and approve access. The CLI stores a short-lived access token and a refresh token in ~/.talentprism/config.toml, a file only your user can read. Tokens refresh on their own. A login is scoped to the team you picked.

On an SSH session or a machine with no browser, run:

tp login --no-browser

The CLI prints a link. Open it on any device, sign in, and approve. Your browser is then sent to a http://127.0.0.1 address that may fail to load. Copy that full address (or just the code) and paste it back into the terminal.

Options: --profile NAME stores the login under a named profile. --base-url URL signs in to a different server.

Check how you are signed in:

tp config get
tp whoami

Sign out:

tp logout

tp logout revokes the tokens on the server and removes them from the config file. If the server cannot be reached, the local tokens are still removed and the CLI says the tokens will expire on their own. You can also see and sign out CLI sign-ins from your account page in TalentPrism.

Automation and agents: API keys

A browser is not available to CI jobs and AI agents, so they use an API key. Create a team-scoped API key from your TalentPrism profile, then set:

export TALENTPRISM_API_KEY="<your api key>"

TALENTPRISM_API_KEY is the preferred path for agents because it does not write a secret into a config file. An API key is scoped to one TalentPrism team. Avoid the --api-key flag: it can leak into shell history and process listings.

When you create an API key you choose how long it is valid: 30 days, 90 days or 1 year (1 year is the default). TalentPrism emails the key's owner 14 days and again 1 day before it expires. Your account page shows each key's expiry date and when it was last used; create a replacement key before the old one expires.

You can also store a key in a named profile:

tp config set work --api-key "<your api key>"
tp config set-profile work

A key or login stops working when its user is deactivated or removed from the team.

Which credential wins

When more than one credential is present, tp uses the first of these:

1. the --api-key flag
2. the TALENTPRISM_API_KEY environment variable
3. login tokens in the profile
4. api_key in the profile

Login tokens are only sent to the server that issued them. Plain http:// base URLs are refused for non-local hosts (see insecure_base_url in Troubleshooting).

Choose a profile with --profile NAME or the TALENTPRISM_PROFILE environment variable.

Read commands

Add --json or --output json to get JSON. Reads change nothing.

tp config get
tp whoami --output json
tp sequences list --output json
tp sequences list --status Active --output json
tp sequences show <sequence_uuid> --output json
tp sequences summary <sequence_uuid> --output json
tp candidates list --sequence <sequence_uuid> --output json
tp candidates engaged --sequence <sequence_uuid> --output json
tp candidates search --query "aircraft assembler North Charleston" --json
tp candidates show <candidate_id> --output json
tp candidates show <candidate_id> --conversations --reminders --json
tp reminders list --owner <user_id> --due today --json
tp campaigns summary <sequence_uuid> --json
tp campaigns next-actions <sequence_uuid> --json
tp campaigns deliverability <sequence_uuid> --json
tp copilot brief --recruiter <user_id> --since yesterday --json
tp copilot ask "What changed in the aircraft assembler campaign?" --json
tp interviews list --sequence <sequence_uuid> --output json
tp interviews show <interview_uuid> --output json
tp metrics --output json
tp metrics --sequence <sequence_uuid> --output json
tp activity summary --days 14 --output json
tp activity summary --days 14 --sequence <sequence_uuid> --json
tp chats summary --days 14 --json
tp chats messages --chat-id <chat_id> --json

List commands stop with too_many_results when a list has more than 100 items. Narrow the query, or add --all to fetch every page.

Evidence reads

These show the record behind a claim. All work at member level.

tp candidates provenance <candidate_id> --field rate_preference --days 90 --json
tp candidates timeline <candidate_id> --kinds chat_message,call --days 30 --limit 50 --json
tp candidates records <candidate_id> --record-type application --days 90 --json
tp leads maturity <candidate_id> --json
tp leads consent-evidence --candidate <candidate_id> --json
tp chats diagnose --chat-id <chat_id> --json
tp recruiter-actions list --unresolved --days 7 --json
tp recruiter-actions show <action_id> --json

• candidates provenance: what we know about a candidate, field by field, and what wrote each value.
• candidates timeline: one chronological view across chats, outreach, calls and other records. --kinds takes a comma-separated list such as chat_message,outreach,call.
• candidates records: whether a specific record exists. --record-type takes a comma-separated list of application, referral, job_alert_subscription, recruiter_handoff, profile_update.
• leads maturity: how complete a lead is, with the missing facts named.
• leads consent-evidence: the sharing decision and the quote behind it. Leave out --candidate for a team-wide check.
• chats diagnose: checks one conversation for duplicate replies, unanswered turns, and repeated recovery messages.
• recruiter-actions list and show: handoffs and alerts, and whether anyone has acted on them.

Team configuration reads

tp team-config read --json
tp team-config read --workflow keepwarm --json
tp team-config senders --json
tp team-config compare --other-team <team_id> --json
tp team-config preview-change --set nudge_enabled=true --json

team-config read and preview-change are open to members. team-config senders and team-config compare are admin only.

Admin diagnostics

tp ops delivery-status --candidate <candidate_id> --channel sms --days 3 --json
tp ops decision-logs --loop nudge --days 3 --json

tp ops delivery-status reports whether messages were actually sent, with the proof field for each send path. tp ops decision-logs reports what the nudge and keep-warm loops decided. Both need the admin role on the team. A member gets not_authorized.

Writes: preview first, then approve

Every write needs two steps. The first step changes nothing.

1. Run the command with no approval flags. The CLI prints a preview of what would happen and a one-time approval token. Exit code is 0.
2. Read the preview. If it is right, run the exact same command again and add --confirm-write --approval-token <token>.

--confirm-write and --approval-token must always be used together. If you pass only one, the CLI stops with preview_bound_approval_required.

The approval token:

• expires after 15 minutes
• can be used once
• is bound to the command and its exact inputs. Change a recipient, message, date, or any other input and you need a new preview.

The server rejects a missing, expired, already-used, or changed-input token. Run the preview again to get a new one.

Worked example. Step 1, preview:

tp candidates add-note 123 --text "Prefers second shift" --json

The output has "status": "approval_required", a preview, and an approval block with the token and its expires_at. Nothing has been saved yet. Step 2, confirm with the same arguments plus the token:

tp candidates add-note 123 --text "Prefers second shift" --confirm-write --approval-token <token> --json

Sending to candidates

send-email and send-sms send a real message to a real candidate, so they also need an idempotency key. If you do not pass one, the CLI generates one for the preview and puts it in the preview output as inputs.idempotency_key. Copy it, and pass it as --idempotency-key on the second run. The CLI refuses the second run without it (idempotency_key_required). Repeating an approved send with the same key returns the original receipt instead of sending twice.

Step 1, preview:

tp candidates send-sms 123 --message "Reply 1 to fast-track." --json

Step 2, send:

tp candidates send-sms 123 --message "Reply 1 to fast-track." --idempotency-key <key from the preview> --confirm-write --approval-token <token> --json

A send to a candidate who has opted out, is inactive, or has an unsubscribed or invalid contact on that channel is refused with recipient_suppressed. Do not retry it.

Write commands

Each command below is shown in its final form (step 2). Run it first without --confirm-write --approval-token <token> to get the preview.

tp candidates add-note <candidate_id> --text "Prefers second shift" --confirm-write --approval-token <token> --json
tp candidates send-email <candidate_id> --subject "Next step" --body "Please use your interview link." --idempotency-key <key> --confirm-write --approval-token <token> --json
tp candidates send-sms <candidate_id> --message "Reply 1 to fast-track." --idempotency-key <key> --confirm-write --approval-token <token> --json
tp reminders create --candidate <candidate_id> --due tomorrow --text "Call about availability" --confirm-write --approval-token <token> --json
tp reminders complete <reminder_id> --confirm-write --approval-token <token> --json
tp interviews create-link --candidate <candidate_id> --sequence <sequence_uuid> --confirm-write --approval-token <token> --json
tp recruiters notify --candidate <candidate_id> --sequence <sequence_uuid> --update "Candidate asked for a callback." --confirm-write --approval-token <token> --json
tp recruiter-actions complete <action_id> --note "Called back" --confirm-write --approval-token <token> --json
tp recruiter-actions escalate <action_id> --reason "Needs a decision today" --confirm-write --approval-token <token> --json
tp team-config update --set nudge_enabled=true --eval-run "<suite, verdict, date>" --confirm-write --approval-token <token> --json

tp team-config update is admin only. A change to agent behavior (model, provider, temperature, reasoning effort, or a worker or tool flag) is refused unless you pass --eval-run (the eval suite and verdict covering the change) or --eval-waiver (why it ships without one). Use tp team-config preview-change first to see what a change would really do.

Optional flags: tp reminders create works without --candidate. tp recruiters notify also accepts --action-needed, --action-tag, --subject, --message and --force-channel. tp candidates send-email and tp candidates send-sms accept --recipient, and send-sms accepts --sequence.

Capabilities

The commands above are shortcuts over the typed capability registry. Use the registry directly to discover what is available:

tp capabilities list --json
tp capabilities mcp --json
tp capabilities commands --json
tp capabilities invoke candidates.search --input-json '{"query":"aircraft assembler"}' --json
tp capabilities preview candidates.add_note --input-json '{"candidate_id":123,"text":"Prefers second shift"}' --json
tp capabilities invoke candidates.add_note --input-json '{"candidate_id":123,"text":"Prefers second shift"}' --confirm-write --approval-token <token> --json
tp capabilities verify candidates.add_note --input-json '{"candidate_id":123,"text":"Prefers second shift"}' --json

• tp capabilities list shows every capability with its schemas, source policy, risk, and field policy.
• tp capabilities mcp shows the same registry as MCP-style tool metadata.
• tp capabilities commands generates tp capabilities invoke ... examples from the live registry, and says which capabilities support preview and verify.
• tp capabilities preview shows what a write would do (recipients, rendered message, sender, exclusions) without doing it. It is a read, so it needs no --confirm-write. For a write capability it also returns an approval token.
• tp capabilities invoke runs a capability. A write capability follows the two-step flow above, with the same --confirm-write --approval-token <token> on the second run. Pass --idempotency-key on both runs when the capability needs one (candidate sends do).
• tp capabilities verify re-reads the stored record a write claims to have produced.

Agent skill

tp skill print

Prints the agent skill text bundled with the CLI. It is also served at /.well-known/agent-skills/talentprism-cli/SKILL.md.

Draft sequence creation

tp sequences create --file <path> accepts a YAML or JSON file with explicit step1, step2, and step3 sections that mirror the TalentPrism sequence wizard APIs. New sequences stay in Draft.

tp sequences create, tp sequences update-step2 and tp sequences update-outreach follow the same two-step flow as every other write. The first run returns a preview and an approval token. The second run adds --confirm-write --approval-token <token>.

tp sequences create --dry-run --file sequence.yaml
tp sequences create --file sequence.yaml
tp sequences create --file sequence.yaml --confirm-write --approval-token <token>
tp sequences update-step2 <sequence_uuid> --file sequence.yaml
tp sequences update-step2 <sequence_uuid> --file sequence.yaml --confirm-write --approval-token <token>
tp sequences update-outreach <sequence_uuid> --file sequence.yaml
tp sequences update-outreach <sequence_uuid> --file sequence.yaml --confirm-write --approval-token <token>

--dry-run is a local check. It reads and validates the file and prints it. It sends nothing to TalentPrism and changes nothing.

Output and errors

Successful command data is written to stdout. Errors and progress notes are written to stderr. Output defaults to JSON when piped and a table in an interactive terminal.

tp metrics --output json
tp sequences list --output yaml
tp candidates list --sequence <sequence_uuid> --output csv

Structured error payloads include code, type, message, details and remediation:

{
  "code": "auth_failed",
  "type": "auth",
  "message": "TalentPrism rejected the API key.",
  "details": {},
  "remediation": "Verify TALENTPRISM_API_KEY is active and scoped to the expected team. API keys expire on the date chosen when they were created: create a new one from your TalentPrism account page, or run `tp login` to sign in as yourself."
}

Exit codes

• 0: success (a write preview also exits 0)
• 2: invalid input
• 3: auth failure
• 4: not found
• 5: validation failure
• 6: transient service failure (includes rate_limited)
• 7: schema mismatch

Rate limits

The server allows 300 reads, 60 changes and 30 copilot questions (tp copilot ask and tp copilot brief) per minute for each credential (each API key, or each login). Limits follow what a request does, not its HTTP method: read commands such as tp chats summary and write previews count as reads even though they are sent as POST requests, and only an approved write counts as a change. When a limit is hit, the CLI reports rate_limited with a retry_after value. The CLI retries reads on its own when the wait is 10 seconds or less. It never retries a POST.

Troubleshooting

Each error has a code. Find it here.

Safety boundaries

Reads are team-scoped and go through Django permissions. Every write goes through a preview and a one-time approval token bound to the exact inputs. The server rejects a missing, expired, reused, cross-team, cross-user, or changed-input token.

What the CLI can do:

• read sequences, candidates, interviews, reminders, campaign and activity data, chats, and evidence records for the signed-in team
• add candidate notes, create and complete reminders, and complete or escalate recruiter actions
• send an email or an SMS to a candidate (tp candidates send-email, tp candidates send-sms), after preview and approval. Sends to opted-out candidates are refused.
• create interview links and notify recruiters
• create and update draft sequences
• change team configuration, if you are a team admin
• run copilot planner prompts

What the CLI does not do:

• It has no command to trigger voice calls, delete data, or pause, resume or delete a sequence.
• It does not bypass Django permissions or team scoping.

tp capabilities invoke can also run any other write capability the server registers for the CLI, always behind the same preview and approval. As of this writing that includes sequence_setup.launch (activates a draft sequence) and candidates.update_profile (changes candidate profile fields). Run tp capabilities list or tp capabilities commands for the live list, and do not run one unless you mean to.

Bot and agent access

This page is public and does not require a TalentPrism login. Public crawlers, documentation checkers, and agent-readiness tools can use it to discover the install, authentication, command, error, and safety contract for the TalentPrism CLI.