Metadata-Version: 2.4
Name: talentprism-cli
Version: 0.3.1
Summary: Command line for TalentPrism: team-scoped recruiting data and actions for people and AI agents
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://talentprism.ai
Project-URL: Documentation, https://talentprism.ai/help/talentprism-cli/
Keywords: talentprism,recruiting,cli,agents
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: talentprism_cli/LICENSE.txt
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: requests>=2.32.0
Dynamic: license-file

# TalentPrism CLI

`tp` is the command line for TalentPrism. It reads team-scoped recruiting data (sequences, candidates, interviews, reminders, campaign and activity summaries, evidence records) and makes changes through the same permissions and validation as the web app. It prints JSON that scripts and AI agents can parse, and reports errors as structured JSON with a stable `code`.

Full documentation: https://talentprism.ai/help/talentprism-cli/

## Install

```shell
pipx install talentprism-cli
# or
uv tool install talentprism-cli

tp --version
```

Requires Python 3.11 or newer.

## Sign in

People sign in with the browser:

```shell
tp login
```

Pick a team and approve. The CLI keeps short-lived tokens in `~/.talentprism/config.toml` and refreshes them on its own. Use `tp login --no-browser` over SSH, and `tp logout` to sign out.

Scripts, CI jobs and AI agents use a team-scoped API key instead:

```shell
export TALENTPRISM_API_KEY="<your api key>"
```

New API keys expire one year after they are created. Your account page shows each key's expiry date and when it was last used; create a replacement key before the old one expires.

When several credentials are present, `tp` uses the first of: the `--api-key` flag, `TALENTPRISM_API_KEY`, login tokens in the profile, `api_key` in the profile. The server is `https://talentprism.ai` unless you set `TALENTPRISM_BASE_URL` (local development only).

## Examples

```shell
tp whoami
tp sequences list --status Active --json
tp candidates search --query "aircraft assembler North Charleston" --json
tp candidates search --query "welder" --limit 20 --json
tp activity summary --days 14 --json
tp candidates timeline <candidate_id> --days 30 --json
```

List commands stop with `too_many_results` when a list has more than 100 items. Add `--limit N` for the first N rows in the server's order (the result keeps `count`, the server's total, and sets `truncated`), or `--all` to fetch every page. The two cannot be combined.

## Changing data

Every write is two steps. Run the command once to get a preview and a one-time approval token. Nothing changes. Then run the same command again with `--confirm-write --approval-token <token>`:

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

## Rate limits

Per credential (each API key, or each login), per minute: 300 reads, 60 changes, and 30 copilot questions (`tp copilot ask` and `tp copilot brief`). Previews count as reads. When a limit is hit the CLI reports `rate_limited` with a `retry_after` value.

## Help

- `tp --help` and `tp <command> --help` list every command and flag.
- `tp skill print` prints the agent skill text bundled with the CLI.
- Errors come with a `remediation` line. The help page has a troubleshooting table keyed by error code.

## License

Proprietary. The CLI is provided for use with a TalentPrism account; see `LICENSE.txt` in the package.
