Metadata-Version: 2.4
Name: theirstack
Version: 0.1.2
Summary: Search TheirStack job postings, companies and technographics from the terminal, scripts and cron.
Author: TheirStack
Project-URL: Homepage, https://theirstack.com
Project-URL: Documentation, https://theirstack.com/en/docs/mcp
Project-URL: MCP tools, https://theirstack.com/en/docs/mcp/tools
Project-URL: API keys, https://theirstack.com/en/docs/api-reference/authentication
Keywords: theirstack,job postings,technographics,company data,mcp,cli
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: fastmcp<5,>=4.1
Requires-Dist: pyyaml>=6.0

The command-line client for [TheirStack](https://theirstack.com). 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.

```bash
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](https://theirstack.com/en/docs/mcp). 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.

```bash
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](https://app.theirstack.com). There are three ways to sign in:

```bash
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](https://app.theirstack.com/settings/api-key). 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](https://theirstack.com/en/docs/pricing/credits).

## Find a tool

```bash
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](https://theirstack.com/en/docs/mcp/tools) 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.

```bash
# 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

```bash
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.

```bash
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](https://theirstack.com/en/docs/mcp).
