The command-line client for TheirStack. Search job postings, companies and the technologies they use from your terminal, a script or a cron job. It talks to TheirStack directly, so there is no LLM in the loop.
uvx theirstack login
uvx theirstack call search_jobs --arg job_title_or='["data engineer"]' --arg limit=10
The CLI is a thin client over the TheirStack MCP server. It reads the server's list of tools every time it runs, so a new API endpoint becomes a new command with no CLI release. The server marks each tool as read-only, write or destructive, and the CLI keeps those apart. You can let an agent run lookups on its own without giving it the ability to change anything.
Install
You need Python 3.12 or later.
uvx theirstack --help # run without installing
uv tool install theirstack # install the `theirstack` command
pip install theirstack # or with pip
uvx theirstack@latest runs the newest release, and uv tool upgrade theirstack updates an installed copy. A plain uvx theirstack or uv tool install theirstack keeps the version you already have.
Sign in
You need a TheirStack account, which you can create at app.theirstack.com. There are three ways to sign in:
theirstack login # OAuth in the browser; the token is stored for next time
theirstack login --no-browser # headless: prints a URL, you paste the redirect back
export THEIRSTACK_API_KEY=ts_… # unattended (CI, cron): an API key, no login
theirstack logout # forget the stored OAuth token
Create an API key in Settings > API Keys. When THEIRSTACK_API_KEY is set, it wins over any stored token.
The OAuth token is written to ~/.theirstack/oauth-tokens.json, created 0600 inside a 0700 directory, and is never printed.
Every call spends your team's API credits at the same rate as the API, for example 1 credit per job and 3 per company returned. See how credits work.
Find a tool
theirstack tools # every tool, with its effect (read/write/destructive)
theirstack tools --search company # filter by name or description
theirstack describe search_jobs # a tool's effect, description and full input schema
theirstack whoami # the signed-in identity and auth status
The MCP tools reference describes each tool with example questions.
Call a tool
call runs read-only tools only, and run runs the rest. An agent permission rule that allows theirstack call * can therefore never reach a write.
# Arguments: --arg key=value (repeatable; a value is JSON when it parses, else a string),
# or a whole JSON object via --json.
theirstack call search_jobs --arg job_title_or='["data engineer"]' --arg limit=10
theirstack call search_jobs --json '{"job_title_or": ["data engineer"], "limit": 10}'
theirstack call search_jobs --json @query.json # from a file
theirstack call search_jobs --json - # from stdin
# A write tool is refused by `call` (exit 4) and run by `run`.
theirstack run create_webhook --arg url=https://example.com/hook
# A destructive tool run by `run` asks for confirmation on a terminal, and fails
# without one (there is no --yes flag).
theirstack run delete_company_list --arg list_id=42
Shape the output
theirstack call search_jobs … -f csv # json | jsonl | csv | yaml | table
theirstack call search_jobs … --select id,job_title,company # keep only these (dotted) fields
theirstack call search_jobs … --out results.csv -f csv # write to a file
theirstack call get_credit_balance -q # suppress the metadata line on stderr
The default format is JSON when the output is piped and a table on a terminal. stdout carries only the records (the array a search returns, or the single object a lookup returns), so a pipe stays clean. Result metadata such as totals and cursors goes to stderr.
Pagination is never automatic. Each page costs credits, so you ask for the next one with the tool's own page argument.
Run a batch from a file
Put one value per line. The CLI sends one request per value and writes the results in the order of the input.
printf 'stripe.com\nshopify.com\n' > domains.txt
theirstack call search_companies --ids domains.txt --ids-arg company_domain_or \
--select name,url,employee_count -f csv
--ids-arg names the argument the values fill. When that argument is a list filter, each value is sent as a one-element list. Use - instead of a path to read the values from stdin.
Exit codes
A script can tell why a run failed without parsing text. Every error also writes a JSON object with a stable shape to stderr: {"error": …, "message": …, "exit_code": …}.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Unexpected internal error |
| 2 | Usage error (bad flags or arguments) |
| 3 | Not authenticated. Run theirstack login or set THEIRSTACK_API_KEY |
| 4 | Refused by the read/write/destructive gate, or a declined confirmation |
| 5 | The server does not offer the requested tool |
| 6 | Could not reach the server or speak MCP to it |
| 7 | The tool ran and the server returned an error (for example a 4xx) |
Point at a different server
THEIRSTACK_MCP_URL overrides the endpoint, which defaults to https://api.theirstack.com/mcp. THEIRSTACK_CONFIG_DIR overrides where the token is stored.
To connect an AI assistant such as Claude, ChatGPT or Cursor instead, follow the MCP server setup.
Metadata
Release files for theirstack 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| theirstack-0.1.2.tar.gz | 25.4 kB | Without provenance | Details for theirstack-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| theirstack-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for theirstack-0.1.2-py3-none-any.whl |
Total release size: 49.7 kB
Release files / theirstack-0.1.2.tar.gz
| Download URL | theirstack-0.1.2.tar.gz |
|---|---|
| Size | 25.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b4059958883d935417ed741f2afbba0608f8b1b31c3be158c316ecadb4a367d4
|
|
BLAKE2b-256 checksum How to use checksums |
c9a1c58190c8693289734786f36808972591625bf241bb94da5482de62a3724c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / theirstack-0.1.2-py3-none-any.whl
| Download URL | theirstack-0.1.2-py3-none-any.whl |
|---|---|
| Size | 24.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
35f120d8983e27f9f63571d1defba7a17644f95817da4791d3952fc049cef942
|
|
BLAKE2b-256 checksum How to use checksums |
7da840eb315f967da894d77ae226df7ce89efc8454b5ecd72ee546174078fb3f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for theirstack 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.