talentprism-cli 0.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,17 @@
1
+ TalentPrism CLI License
2
+
3
+ Copyright (c) 2026 TalentPrism. All rights reserved.
4
+
5
+ This software is provided for use with a TalentPrism account, under the
6
+ TalentPrism terms of service. You may install and run it on systems you
7
+ control to access TalentPrism services that you are authorized to use.
8
+
9
+ You may not modify, copy, redistribute, sublicense or sell this software,
10
+ or use it to access TalentPrism other than through your own authorized
11
+ account, without prior written permission from TalentPrism.
12
+
13
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
16
+ TALENTPRISM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
17
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
@@ -0,0 +1,70 @@
1
+ # TalentPrism CLI
2
+
3
+ `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`.
4
+
5
+ Full documentation: https://talentprism.ai/help/talentprism-cli/
6
+
7
+ ## Install
8
+
9
+ ```shell
10
+ pipx install talentprism-cli
11
+ # or
12
+ uv tool install talentprism-cli
13
+
14
+ tp --version
15
+ ```
16
+
17
+ Requires Python 3.11 or newer.
18
+
19
+ ## Sign in
20
+
21
+ People sign in with the browser:
22
+
23
+ ```shell
24
+ tp login
25
+ ```
26
+
27
+ 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.
28
+
29
+ Scripts, CI jobs and AI agents use a team-scoped API key instead:
30
+
31
+ ```shell
32
+ export TALENTPRISM_API_KEY="<your api key>"
33
+ ```
34
+
35
+ 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.
36
+
37
+ 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).
38
+
39
+ ## Examples
40
+
41
+ ```shell
42
+ tp whoami
43
+ tp sequences list --status Active --json
44
+ tp candidates search --query "aircraft assembler North Charleston" --json
45
+ tp activity summary --days 14 --json
46
+ tp candidates timeline <candidate_id> --days 30 --json
47
+ ```
48
+
49
+ ## Changing data
50
+
51
+ 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>`:
52
+
53
+ ```shell
54
+ tp candidates add-note 123 --text "Prefers second shift"
55
+ tp candidates add-note 123 --text "Prefers second shift" --confirm-write --approval-token <token>
56
+ ```
57
+
58
+ ## Rate limits
59
+
60
+ 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.
61
+
62
+ ## Help
63
+
64
+ - `tp --help` and `tp <command> --help` list every command and flag.
65
+ - `tp skill print` prints the agent skill text bundled with the CLI.
66
+ - Errors come with a `remediation` line. The help page has a troubleshooting table keyed by error code.
67
+
68
+ ## License
69
+
70
+ Proprietary. The CLI is provided for use with a TalentPrism account; see `LICENSE.txt` in the package.
@@ -0,0 +1 @@
1
+ __version__ = "0.3.0"
@@ -0,0 +1,5 @@
1
+ from .cli import main
2
+
3
+
4
+ if __name__ == "__main__":
5
+ raise SystemExit(main())
@@ -0,0 +1,222 @@
1
+ """`tp login` (OAuth authorization code + PKCE, loopback redirect) and `tp logout`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import secrets
7
+ import sys
8
+ import time
9
+ import webbrowser
10
+ from pathlib import Path
11
+ from typing import Any, Callable, TextIO
12
+
13
+ from . import oauth
14
+ from .config import (
15
+ TalentPrismConfig,
16
+ parse_expiry,
17
+ resolve_base_url,
18
+ select_profile,
19
+ transport_settings,
20
+ validate_base_url_scheme,
21
+ )
22
+ from .config_store import config_path as resolve_config_path
23
+ from .config_store import load_config
24
+ from .credentials import clear_login, save_client, save_login
25
+ from .errors import TalentPrismError
26
+ from .loopback import (
27
+ LOGIN_TIMEOUT_SECONDS,
28
+ CallbackServer,
29
+ check_callback,
30
+ free_port_redirect_uri,
31
+ read_pasted_redirect,
32
+ )
33
+ from .transport import APIClient, RequestFn
34
+
35
+
36
+ def login(
37
+ *,
38
+ base_url: str | None,
39
+ profile: str | None,
40
+ config_path: str | Path | None,
41
+ env: dict[str, str] | None,
42
+ no_browser: bool,
43
+ request: RequestFn | None,
44
+ stderr: TextIO,
45
+ stdin: TextIO | None = None,
46
+ open_browser: Callable[[str], bool] = webbrowser.open,
47
+ timeout: float = LOGIN_TIMEOUT_SECONDS,
48
+ ) -> dict[str, Any]:
49
+ env = os.environ if env is None else env
50
+ request = request or _requests_request()
51
+ path = resolve_config_path(config_path)
52
+ file_config = load_config(path)
53
+ profile_name = select_profile(file_config, profile, env)
54
+ profile_config = file_config.get("profiles", {}).get(profile_name, {})
55
+ base, _source = resolve_base_url(base_url, env, profile_config)
56
+ base = base.rstrip("/")
57
+ validate_base_url_scheme(base, env)
58
+ insecure_ok = env.get("TALENTPRISM_ALLOW_INSECURE_HTTP") == "1"
59
+ settings = transport_settings(env)
60
+ api_timeout = settings["timeout_seconds"]
61
+
62
+ stored = (
63
+ profile_config.get("oauth_client_id") if profile_config.get("oauth_base_url", "").rstrip("/") == base else ""
64
+ )
65
+ for attempt in (1, 2):
66
+ client_id = stored or oauth.register_client(base, request=request, insecure_ok=insecure_ok, timeout=api_timeout)
67
+ if not stored:
68
+ save_client(path, profile_name, client_id=client_id, base_url=base)
69
+ try:
70
+ tokens = _authorize(
71
+ base,
72
+ client_id,
73
+ request,
74
+ insecure_ok,
75
+ api_timeout,
76
+ no_browser,
77
+ stderr,
78
+ stdin or sys.stdin,
79
+ open_browser,
80
+ timeout,
81
+ )
82
+ break
83
+ except TalentPrismError as exc:
84
+ if not (stored and attempt == 1 and oauth.oauth_error_code(exc) == "invalid_client"):
85
+ raise
86
+ # The server no longer knows our stored client: forget it and register a fresh one.
87
+ clear_login(path, profile_name, forget_client=True)
88
+ stored = ""
89
+ save_login(path, profile_name, tokens, base_url=base, client_id=client_id)
90
+ return _signed_in_payload(base, profile_name, path, tokens, client_id, request, stderr, insecure_ok, settings)
91
+
92
+
93
+ def logout(
94
+ *,
95
+ base_url: str | None,
96
+ profile: str | None,
97
+ config_path: str | Path | None,
98
+ env: dict[str, str] | None,
99
+ request: RequestFn | None,
100
+ ) -> dict[str, Any]:
101
+ env = os.environ if env is None else env
102
+ path = resolve_config_path(config_path)
103
+ if not path.exists():
104
+ return {"status": "not_logged_in"}
105
+ profile_name = select_profile(load_config(path), profile, env)
106
+ removed = clear_login(path, profile_name) # local tokens go first so a revoke failure cannot keep them alive
107
+ if not (removed.get("access_token") or removed.get("refresh_token")):
108
+ return {"status": "not_logged_in", "profile": profile_name}
109
+ request = request or _requests_request()
110
+ base = removed.get("oauth_base_url") or resolve_base_url(base_url, env, {})[0]
111
+ revoked = True
112
+ for token in (removed.get("refresh_token"), removed.get("access_token")):
113
+ if not token:
114
+ continue
115
+ try:
116
+ oauth.revoke_token(
117
+ base,
118
+ client_id=removed.get("oauth_client_id", ""),
119
+ token=token,
120
+ request=request,
121
+ insecure_ok=env.get("TALENTPRISM_ALLOW_INSECURE_HTTP") == "1",
122
+ timeout=transport_settings(env)["timeout_seconds"],
123
+ )
124
+ except TalentPrismError:
125
+ revoked = False
126
+ payload: dict[str, Any] = {"status": "logged_out", "profile": profile_name, "revoked": revoked}
127
+ if not revoked:
128
+ payload["message"] = (
129
+ "Local tokens were removed, but TalentPrism could not confirm revocation on the server; "
130
+ "the tokens will expire on their own."
131
+ )
132
+ return payload
133
+
134
+
135
+ def _authorize(base, client_id, request, insecure_ok, timeout, no_browser, stderr, stdin, open_browser, wait_timeout):
136
+ verifier = oauth.new_verifier()
137
+ state = secrets.token_urlsafe(24)
138
+ server = None if no_browser else CallbackServer()
139
+ if server:
140
+ server.start()
141
+ redirect_uri = free_port_redirect_uri() if server is None else server.redirect_uri
142
+ url = oauth.authorize_url(
143
+ base, client_id=client_id, redirect_uri=redirect_uri, state=state, challenge=oauth.code_challenge(verifier)
144
+ )
145
+ bare = False
146
+ try:
147
+ if server is None:
148
+ stderr.write(
149
+ "Open this URL in a browser and sign in:\n\n"
150
+ f"{url}\n\n"
151
+ "The browser will then be sent to a http://127.0.0.1 address that may fail to load. "
152
+ "Copy that full address (or just the code) and paste it here:\n> "
153
+ )
154
+ stderr.flush()
155
+ params, bare = read_pasted_redirect(stdin)
156
+ else:
157
+ if _open(open_browser, url):
158
+ stderr.write("Opening your browser to sign in to TalentPrism...\n")
159
+ else:
160
+ stderr.write(
161
+ f"Could not open a browser. Open this URL to sign in (or re-run with --no-browser):\n\n{url}\n\n"
162
+ )
163
+ stderr.flush()
164
+ params = server.wait(wait_timeout)
165
+ finally:
166
+ if server is not None:
167
+ server.close()
168
+ code = check_callback(params, state, bare_code=bare)
169
+ return oauth.exchange_code(
170
+ base,
171
+ client_id=client_id,
172
+ code=code,
173
+ verifier=verifier,
174
+ redirect_uri=redirect_uri,
175
+ request=request,
176
+ insecure_ok=insecure_ok,
177
+ timeout=timeout,
178
+ )
179
+
180
+
181
+ def _open(open_browser: Callable[[str], bool], url: str) -> bool:
182
+ try:
183
+ return bool(open_browser(url))
184
+ except Exception: # noqa: BLE001 - a broken browser launcher must fall back to printing the URL
185
+ return False
186
+
187
+
188
+ def _signed_in_payload(
189
+ base, profile_name, path, tokens, client_id, request, stderr, insecure_ok, settings
190
+ ) -> dict[str, Any]:
191
+ config = TalentPrismConfig(
192
+ api_key="",
193
+ base_url=base,
194
+ profile=profile_name,
195
+ auth_kind="login",
196
+ access_token=str(tokens["access_token"]),
197
+ refresh_token=str(tokens.get("refresh_token", "")),
198
+ token_expires_at=parse_expiry(str(_expiry(tokens))),
199
+ oauth_client_id=client_id,
200
+ config_path=str(path),
201
+ allow_insecure_http=insecure_ok,
202
+ **settings,
203
+ )
204
+ payload: dict[str, Any] = {"status": "logged_in", "profile": profile_name, "base_url": base}
205
+ try:
206
+ identity = APIClient(config, request=request).get("/api/whoami/")
207
+ except TalentPrismError as exc:
208
+ stderr.write(f"Signed in, but could not confirm identity: {exc.message}\n")
209
+ return payload
210
+ if isinstance(identity, dict):
211
+ payload.update({key: identity[key] for key in ("user", "team") if key in identity})
212
+ return payload
213
+
214
+
215
+ def _expiry(tokens: dict[str, Any]) -> float:
216
+ return time.time() + float(tokens.get("expires_in") or 0)
217
+
218
+
219
+ def _requests_request() -> RequestFn:
220
+ import requests
221
+
222
+ return requests.request