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.

Changelog

0.1.3

  • The package declares the MIT license.
  • Releases carry PEP 740 attestations, so PyPI shows where each file was built.
  • Tested on Python 3.12, 3.13 and 3.14.

0.1.2

  • This page describes the CLI and links to the TheirStack docs.

0.1.1

  • theirstack login ends on a TheirStack page in the browser.

0.1.0

  • First release.

Metadata

Release files for theirstack 0.1.3

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.3
File Size Uploaded Provenance Actions
theirstack-0.1.3.tar.gz 26.5 kB With provenance Details for theirstack-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for theirstack 0.1.3
File Interpreter ABI Platform Actions
theirstack-0.1.3-py3-none-any.whl Python 3 none any Details for theirstack-0.1.3-py3-none-any.whl

Total release size: 51.8 kB

Release files / theirstack-0.1.3.tar.gz

Download URL theirstack-0.1.3.tar.gz
Size 26.5 kB
Tags Source
SHA-256 checksum
How to use checksums
f1fbac33a085dd9b958b83bb894f6bcffb18a380dc5caf04ea9f223f48c1c31c
BLAKE2b-256 checksum
How to use checksums
8398150c32bd44a768b2d66886b9fe461c0bdbb56d01323c63738558d440b838
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / theirstack-0.1.3-py3-none-any.whl

Download URL theirstack-0.1.3-py3-none-any.whl
Size 25.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9efd37dc57da97bdddfce48f0257ace59d38dc762d4186de5fbec62c5b40c02e
BLAKE2b-256 checksum
How to use checksums
ad1dad994a28c310b4ef0fe9934a2e26af3374220e35940767c308f5e89af120
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for theirstack 0.1.3

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for theirstack-0.1.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

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