CLI
Search jobs, companies and tech stacks from your terminal, shell scripts and cron jobs with the theirstack command line tool. Every MCP tool is a command, with JSON, CSV or table output.
theirstack is our command line tool. It gives you the same data as the API and the MCP server (jobs, companies, technologies, saved searches, webhooks, credits) in a terminal, a shell script or a cron job, with no AI client in between.
uvx theirstack call search_jobs --arg job_title_or='["data engineer"]' --arg limit=5The CLI asks our MCP server for its tools each time it runs, so new tools show up as commands without updating the CLI.
Install
The CLI is a Python package on PyPI. The simplest way to run it is with uv:
uvx theirstack --help # run it without installing
uv tool install theirstack # or install the theirstack commandTo update it later, run uv tool upgrade theirstack, or uvx theirstack@latest if you don't install it. pipx install theirstack works too.
Sign in
There are three ways to sign in, checked in this order:
export THEIRSTACK_API_KEY=<YOUR_API_KEY> # scripts, CI and cron: no login needed
theirstack login # OAuth in your browser; the token is kept for next time
theirstack login --no-browser # on a server: open the printed URL elsewhere and paste the redirect backGet an API key from app.theirstack.com → API Keys. When THEIRSTACK_API_KEY is set, it wins over a stored login. The OAuth token is saved in ~/.theirstack/oauth-tokens.json, readable only by you, and theirstack logout deletes it. theirstack whoami shows who you are signed in as.
Find a tool
theirstack tools # every tool, and whether it reads, writes or deletes
theirstack tools --search company # only tools whose name or description matches
theirstack describe search_jobs # what a tool does and every argument it takesThe arguments of each tool are the same as those of its API endpoint, and the tools reference links every tool to its endpoint.
Run a tool
There are two commands, so you can decide what a script or an AI agent is allowed to change:
theirstack callruns tools that only read data, such as searches, lookups, catalogs and your credit balance. It refuses any tool that changes something.theirstack runruns every tool, including those that create, update or delete. A tool that deletes something asks you to confirm in the terminal, and fails when there is no terminal to ask. There is no flag to skip that.
# Arguments one by one: a value is read as JSON when it is valid JSON, and as text otherwise
theirstack call search_jobs --arg job_title_or='["data engineer"]' --arg posted_at_max_age_days=7 --arg limit=10
# Or all of them as one JSON object: inline, from a file or from stdin
theirstack call search_jobs --json '{"job_title_or": ["data engineer"], "limit": 10}'
theirstack call search_jobs --json @query.json
cat query.json | theirstack call search_jobs --json -
# Tools that change something go through run
theirstack run create_webhook --arg search_id=123 --arg url=https://example.com/hookThis split matters when you let a coding agent like Claude Code or Codex use the CLI. Allow theirstack call * and the agent can look anything up, but it can never create, change or delete anything in your account.
Choose the output
theirstack call search_jobs --json @query.json -f csv --out jobs.csv
theirstack call search_companies --arg company_domain_or='["stripe.com"]' --select name,employee_count,country
theirstack call get_credit_balance -q-f/--format:json,jsonl,csv,yamlortable. It defaults to a table in a terminal and to JSON when you pipe the output.--select: keep only the fields you list, with dots for nested ones (company_object.name).--out: write the results to a file.-q: hide the credits used and other details printed to stderr.
Only the results go to stdout. Totals, the credits a call used and other details go to stderr, so piping into jq or another command keeps working.
The CLI never fetches more pages on its own, because each page uses credits. Ask for the next one with the tool's page argument.
Look up a list of values
Put one value per line in a file and the CLI makes one call per value, returning the results in the same order:
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 is the argument each value goes into. When that argument takes a list, each value is sent as a list of one. Use --ids - to read the values from stdin.
Handle errors in scripts
Each kind of failure has its own exit code, and the CLI also writes the error to stderr as JSON ({"error": …, "message": …, "exit_code": …}), so a script can react without parsing text.
| Exit code | Meaning |
|---|---|
| 0 | Success |
| 1 | Unexpected error in the CLI |
| 2 | Wrong command, flag or argument |
| 3 | Not signed in. Run theirstack login or set THEIRSTACK_API_KEY |
| 4 | Refused, because call was asked to run a tool that writes or a deletion was not confirmed |
| 5 | The server has no tool with that name |
| 6 | Could not reach the server |
| 7 | The tool ran and returned an error, such as an invalid argument |
Pricing
The CLI is free. Each tool call uses credits at the same rate as the API call behind it, just like the MCP server. See how credits work.
FAQs
How is this guide?
Last updated on
