Skip to main content

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)

Source distribution for theirstack 0.1.2
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)

Table of built distributions (wheels) for theirstack 0.1.2
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page