theirstack 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,8 @@
1
+ Metadata-Version: 2.4
2
+ Name: theirstack
3
+ Version: 0.1.0
4
+ Summary: TheirStack CLI — query TheirStack's job, company and technographic data from the terminal, scripts and cron, over the TheirStack MCP server.
5
+ Requires-Python: >=3.12
6
+ Requires-Dist: click>=8.1
7
+ Requires-Dist: fastmcp<5,>=4.1
8
+ Requires-Dist: pyyaml>=6.0
@@ -0,0 +1,142 @@
1
+ # theirstack — the TheirStack CLI
2
+
3
+ Query TheirStack's job, company and technographic data from the terminal, from
4
+ scripts and from cron — no LLM in the loop. It is a thin client over the
5
+ [TheirStack MCP server](https://api.theirstack.com/mcp): it lists the server's
6
+ tools at runtime, so a new API endpoint becomes a new command with no CLI
7
+ release, and it splits those tools by the server's own annotations so an agent
8
+ can be allowed read-only access without the ability to write.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ uvx theirstack --help # run without installing
14
+ uv tool install theirstack # install the `theirstack` command
15
+ ```
16
+
17
+ ## Authenticate
18
+
19
+ Three ways in, in priority order:
20
+
21
+ ```bash
22
+ theirstack login # OAuth in the browser; token stored for next time
23
+ theirstack login --no-browser # headless: prints a URL, you paste the redirect back
24
+ export THEIRSTACK_API_KEY=ts_… # unattended (CI, cron): a bearer token, no login
25
+ theirstack logout # forget the stored OAuth token
26
+ ```
27
+
28
+ The OAuth token is written to `~/.theirstack/oauth-tokens.json`, created `0600`
29
+ inside a `0700` directory, and is never printed. `THEIRSTACK_API_KEY`, when set,
30
+ wins over any stored token.
31
+
32
+ ## Discover
33
+
34
+ ```bash
35
+ theirstack tools # every tool, with its effect (read/write/destructive)
36
+ theirstack tools --search company # filter by name or description
37
+ theirstack describe search_jobs # a tool's effect, description and full input schema
38
+ theirstack whoami # the signed-in identity / auth status
39
+ ```
40
+
41
+ ## Call
42
+
43
+ `call` runs **read-only** tools only; `run` runs the rest. This is the agent-safety
44
+ split: a permission rule that allows `theirstack call *` can never reach a write.
45
+
46
+ ```bash
47
+ # Arguments: --arg key=value (repeatable; a value is JSON when it parses, else a string),
48
+ # or a whole JSON object via --json.
49
+ theirstack call search_jobs --arg job_title_or='["data engineer"]' --arg limit=10
50
+ theirstack call search_jobs --json '{"job_title_or": ["data engineer"], "limit": 10}'
51
+ theirstack call search_jobs --json @query.json # from a file
52
+ theirstack call search_jobs --json - # from stdin
53
+
54
+ # A write tool is refused by `call` (exit 4) and run by `run`.
55
+ theirstack run create_webhook --arg url=https://example.com/hook
56
+
57
+ # A destructive tool run by `run` asks for confirmation on a terminal, and fails
58
+ # without one (no --yes flag). An allow-listed read stays safe to automate.
59
+ theirstack run delete_company_list --arg list_id=42
60
+ ```
61
+
62
+ ## Shape the output
63
+
64
+ ```bash
65
+ theirstack call search_jobs … -f csv # json | jsonl | csv | yaml | table
66
+ theirstack call search_jobs … --select id,job_title,company # keep only these (dotted) fields
67
+ theirstack call search_jobs … --out results.csv -f csv # write to a file
68
+ theirstack call get_credit_balance -q # suppress the metadata line on stderr
69
+ ```
70
+
71
+ Default format is **json when piped** and **table on a terminal**. stdout carries
72
+ only the records (the array a search returns, or the single object a lookup
73
+ returns), so a pipe stays clean; result metadata (totals, cursors) goes to stderr.
74
+
75
+ Pagination is never automatic — each page costs credits, so you ask for the next
76
+ one explicitly with the tool's own `page` argument.
77
+
78
+ ## Batch from a file
79
+
80
+ One value per line, one request each, output in the input's order:
81
+
82
+ ```bash
83
+ printf 'stripe.com\nshopify.com\n' > domains.txt
84
+ theirstack call search_companies --ids domains.txt --ids-arg company_domain_or \
85
+ --select name,url,employee_count -f csv
86
+ ```
87
+
88
+ `--ids-arg` names the argument the values fill. When that argument is a list
89
+ filter, each value is sent as a one-element list. Use `-` instead of a path to
90
+ read the values from stdin.
91
+
92
+ ## Exit codes
93
+
94
+ A script can branch on _why_ a run failed without parsing text. Every error also
95
+ writes a stable JSON object to stderr (`{"error": …, "message": …, "exit_code": …}`).
96
+
97
+ | Code | Meaning |
98
+ | ---- | ----------------------------------------------------------------------- |
99
+ | 0 | Success |
100
+ | 1 | Unexpected internal error |
101
+ | 2 | Usage error (bad flags or arguments) |
102
+ | 3 | Not authenticated — run `theirstack login`, or set `THEIRSTACK_API_KEY` |
103
+ | 4 | Refused by the read/write/destructive gate (or a declined confirmation) |
104
+ | 5 | The requested tool is not offered by the server |
105
+ | 6 | Could not reach or speak MCP to the server |
106
+ | 7 | The tool ran and the server returned an error (e.g. a 4xx) |
107
+
108
+ ## Point at a different server
109
+
110
+ `THEIRSTACK_MCP_URL` overrides the endpoint (a PR preview, a local backend).
111
+ `THEIRSTACK_CONFIG_DIR` overrides where the token cache lives.
112
+
113
+ ## Publishing
114
+
115
+ Releases go to PyPI from CI, and there is no API token anywhere. PyPI does not
116
+ trust this monorepo: it trusts the private mirror
117
+ [`TheirStack/theirstack-cli`](https://github.com/TheirStack/theirstack-cli),
118
+ which only holds this package.
119
+
120
+ On every merge to `main` that touches `apps/cli/`,
121
+ `.github/workflows/publish-cli.yml` rebuilds the mirror's tree with
122
+ `mirror/build.sh` and pushes it. When `pyproject.toml` carries a version the
123
+ mirror has no `v<version>` tag for, it also pushes that tag, and the mirror's
124
+ `.github/workflows/publish.yml` (source: `mirror/.github/workflows/publish.yml`)
125
+ builds the sdist and wheel and uploads them with PyPI Trusted Publishing (OIDC)
126
+ from its `pypi` environment, which only accepts `v*` tags.
127
+
128
+ So a release is a merged version bump:
129
+
130
+ ```bash
131
+ # 1. Bump the version in apps/cli/pyproject.toml, e.g. 0.1.0 -> 0.1.1
132
+ # 2. Refresh the lockfile so it records the new version, and commit both:
133
+ cd apps/cli && uv lock
134
+ git commit -am "chore(cli): release v0.1.1"
135
+ # 3. Open the PR as usual. Merging it publishes v0.1.1.
136
+ ```
137
+
138
+ Changes merged without a version bump reach the mirror but are not released.
139
+ Never edit the mirror directly: every sync overwrites it. After a release,
140
+ `uvx theirstack@latest` runs the new version and `uv tool upgrade theirstack`
141
+ updates an existing installation (a plain `uvx theirstack` or
142
+ `uv tool install theirstack` keeps the version already installed).
@@ -0,0 +1,56 @@
1
+ [project]
2
+ name = "theirstack"
3
+ version = "0.1.0"
4
+ description = "TheirStack CLI — query TheirStack's job, company and technographic data from the terminal, scripts and cron, over the TheirStack MCP server."
5
+ requires-python = ">=3.12"
6
+ dependencies = [
7
+ "click>=8.1",
8
+ # The CLI is a thin client over the TheirStack MCP server: fastmcp's Client
9
+ # gives us tool discovery, OAuth (browser + token storage) and tool calls, so
10
+ # a new MCP tool reaches the CLI with no release. Pinned to the same major the
11
+ # backend serves (apps/back pins fastmcp==4.1.6) so client and server agree on
12
+ # the protocol.
13
+ "fastmcp>=4.1,<5",
14
+ "pyyaml>=6.0",
15
+ ]
16
+
17
+ [project.scripts]
18
+ theirstack = "theirstack_cli.cli:main"
19
+
20
+ [dependency-groups]
21
+ dev = [
22
+ "pytest>=8.0",
23
+ "pytest-asyncio>=0.24",
24
+ "ruff>=0.6",
25
+ # Pinned to the same version as apps/back and apps/odoo so the type checker
26
+ # behaves identically across every Python app in the monorepo.
27
+ "ty==0.0.21",
28
+ ]
29
+
30
+ [build-system]
31
+ requires = ["setuptools>=45", "wheel"]
32
+ build-backend = "setuptools.build_meta"
33
+
34
+ [tool.setuptools.packages.find]
35
+ where = ["src"]
36
+ include = ["theirstack_cli", "theirstack_cli.*"]
37
+
38
+ [tool.pytest.ini_options]
39
+ testpaths = ["tests"]
40
+ pythonpath = ["."]
41
+ asyncio_mode = "auto"
42
+ asyncio_default_fixture_loop_scope = "function"
43
+
44
+ [tool.ruff]
45
+ # Inherit the monorepo-wide Python lint baseline (line-length, target-version,
46
+ # the shared select/ignore core). See /ruff-base.toml.
47
+ extend = "ruff-base.toml"
48
+
49
+ [tool.ty.environment]
50
+ python-version = "3.12"
51
+
52
+ [tool.ty.src]
53
+ exclude = ["tests"]
54
+
55
+ [tool.ty.terminal]
56
+ error-on-warning = false
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,8 @@
1
+ Metadata-Version: 2.4
2
+ Name: theirstack
3
+ Version: 0.1.0
4
+ Summary: TheirStack CLI — query TheirStack's job, company and technographic data from the terminal, scripts and cron, over the TheirStack MCP server.
5
+ Requires-Python: >=3.12
6
+ Requires-Dist: click>=8.1
7
+ Requires-Dist: fastmcp<5,>=4.1
8
+ Requires-Dist: pyyaml>=6.0
@@ -0,0 +1,24 @@
1
+ README.md
2
+ pyproject.toml
3
+ src/theirstack.egg-info/PKG-INFO
4
+ src/theirstack.egg-info/SOURCES.txt
5
+ src/theirstack.egg-info/dependency_links.txt
6
+ src/theirstack.egg-info/entry_points.txt
7
+ src/theirstack.egg-info/requires.txt
8
+ src/theirstack.egg-info/top_level.txt
9
+ src/theirstack_cli/__init__.py
10
+ src/theirstack_cli/args.py
11
+ src/theirstack_cli/auth.py
12
+ src/theirstack_cli/cli.py
13
+ src/theirstack_cli/config.py
14
+ src/theirstack_cli/errors.py
15
+ src/theirstack_cli/mcp_client.py
16
+ src/theirstack_cli/operations.py
17
+ src/theirstack_cli/output.py
18
+ src/theirstack_cli/token_store.py
19
+ tests/test_args.py
20
+ tests/test_cli.py
21
+ tests/test_mcp_client.py
22
+ tests/test_operations.py
23
+ tests/test_output.py
24
+ tests/test_token_store.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ theirstack = theirstack_cli.cli:main
@@ -0,0 +1,3 @@
1
+ click>=8.1
2
+ fastmcp<5,>=4.1
3
+ pyyaml>=6.0
@@ -0,0 +1 @@
1
+ theirstack_cli
File without changes
@@ -0,0 +1,70 @@
1
+ """Building a tool's argument object from the command line.
2
+
3
+ Three sources, combined: a JSON object (``--json '<obj>'``, ``--json @file`` or
4
+ stdin) as the base, then ``--arg key=value`` pairs layered on top. A value is
5
+ parsed as JSON when it can be (so numbers, booleans and arrays work) and kept as
6
+ a string otherwise. A repeated key becomes a list, in the order given.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ from typing import Any
13
+
14
+ from theirstack_cli.errors import EXIT_USAGE, CliError
15
+
16
+
17
+ def coerce_value(raw: str) -> Any:
18
+ """`--arg` values are JSON when parseable (3, true, [1,2]), else plain strings."""
19
+ try:
20
+ return json.loads(raw)
21
+ except (json.JSONDecodeError, ValueError):
22
+ return raw
23
+
24
+
25
+ def parse_arg_pairs(pairs: tuple[str, ...]) -> dict[str, Any]:
26
+ result: dict[str, Any] = {}
27
+ for pair in pairs:
28
+ if "=" not in pair:
29
+ raise CliError(
30
+ f"--arg must be key=value, got {pair!r}",
31
+ code=EXIT_USAGE,
32
+ type="usage_error",
33
+ )
34
+ key, raw = pair.split("=", 1)
35
+ value = coerce_value(raw)
36
+ if key in result:
37
+ existing = result[key]
38
+ if isinstance(existing, list):
39
+ existing.append(value)
40
+ else:
41
+ result[key] = [existing, value]
42
+ else:
43
+ result[key] = value
44
+ return result
45
+
46
+
47
+ def parse_json_object(blob: str | None) -> dict[str, Any]:
48
+ if blob is None:
49
+ return {}
50
+ try:
51
+ parsed = json.loads(blob)
52
+ except json.JSONDecodeError as exc:
53
+ raise CliError(
54
+ f"--json is not valid JSON: {exc}", code=EXIT_USAGE, type="usage_error"
55
+ ) from exc
56
+ if not isinstance(parsed, dict):
57
+ raise CliError(
58
+ "--json must be a JSON object (a {...} with named arguments)",
59
+ code=EXIT_USAGE,
60
+ type="usage_error",
61
+ )
62
+ return parsed
63
+
64
+
65
+ def build_arguments(
66
+ arg_pairs: tuple[str, ...], json_blob: str | None
67
+ ) -> dict[str, Any]:
68
+ arguments = parse_json_object(json_blob)
69
+ arguments.update(parse_arg_pairs(arg_pairs))
70
+ return arguments
@@ -0,0 +1,126 @@
1
+ """Resolving how the CLI authenticates to the MCP server.
2
+
3
+ Three ways in, in priority order:
4
+
5
+ 1. ``THEIRSTACK_API_KEY`` — forwarded as a bearer token. The unattended path
6
+ (CI, cron): no browser, no stored state.
7
+ 2. A stored OAuth token from a previous ``theirstack login``.
8
+ 3. The interactive OAuth flow itself, which only ``theirstack login`` starts —
9
+ in the browser, or ``--no-browser`` for a machine without one.
10
+
11
+ Non-login commands never open a browser: if the stored token is gone or cannot
12
+ be refreshed, they fail with an "authentication required" error telling the user
13
+ to log in again, rather than silently launching a browser mid-script.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import sys
19
+ from urllib.parse import parse_qs, urlparse
20
+
21
+ import anyio
22
+ from fastmcp.client.auth import OAuth
23
+ from fastmcp.client.auth.oauth import AuthorizationCodeResult
24
+
25
+ from theirstack_cli import config
26
+ from theirstack_cli.errors import EXIT_AUTH, CliError
27
+ from theirstack_cli.token_store import FileTokenStore
28
+
29
+ CLIENT_NAME = "TheirStack CLI"
30
+
31
+
32
+ class _AuthRequired(CliError):
33
+ def __init__(self, message: str) -> None:
34
+ super().__init__(message, code=EXIT_AUTH, type="authentication_required")
35
+
36
+
37
+ class StoredOAuth(OAuth):
38
+ """OAuth that uses stored tokens but never falls back to a browser.
39
+
40
+ Used by every command except ``login``. Reaching the redirect step means the
41
+ stored session is gone or unrefreshable, so instead of opening a browser in
42
+ the middle of a script we fail and point the user back at ``login``.
43
+ """
44
+
45
+ async def redirect_handler(self, authorization_url: str) -> None:
46
+ raise _AuthRequired(
47
+ "Your session has expired. Run `theirstack login` to sign in again."
48
+ )
49
+
50
+
51
+ class NoBrowserOAuth(OAuth):
52
+ """OAuth for a machine with no browser: print the URL, read the redirect back.
53
+
54
+ The user opens the printed URL on another device, approves, and is redirected
55
+ to a ``localhost`` URL that won't load here — but its address bar holds the
56
+ ``?code=…&state=…`` we need. They paste that whole URL back.
57
+ """
58
+
59
+ async def redirect_handler(self, authorization_url: str) -> None:
60
+ print(
61
+ "\nOpen this URL in a browser and approve access:\n\n"
62
+ f" {authorization_url}\n\n"
63
+ "You will be redirected to a localhost URL that will not load — that "
64
+ "is expected.\nCopy that URL from the address bar and paste it below.",
65
+ file=sys.stderr,
66
+ )
67
+
68
+ async def callback_handler(self) -> AuthorizationCodeResult:
69
+ pasted = await anyio.to_thread.run_sync(
70
+ lambda: input("\nPaste the redirect URL here: ")
71
+ )
72
+ query = parse_qs(urlparse(pasted.strip()).query)
73
+ code = query.get("code", [None])[0]
74
+ state = query.get("state", [None])[0]
75
+ if not code:
76
+ raise _AuthRequired(
77
+ "No authorization code found in the pasted URL. It should look "
78
+ "like http://localhost:PORT/callback?code=...&state=..."
79
+ )
80
+ return AuthorizationCodeResult(
81
+ code=code, state=state, iss=query.get("iss", [None])[0]
82
+ )
83
+
84
+
85
+ def token_store() -> FileTokenStore:
86
+ return FileTokenStore(config.token_file())
87
+
88
+
89
+ def is_logged_in() -> bool:
90
+ return config.api_key() is not None or token_store().has_tokens()
91
+
92
+
93
+ def logout() -> bool:
94
+ """Forget the stored OAuth token. Returns whether anything was stored."""
95
+ store = token_store()
96
+ had = store.has_tokens()
97
+ store.clear()
98
+ return had
99
+
100
+
101
+ def auth_for_commands() -> str | OAuth:
102
+ """The auth to attach to the client for a non-``login`` command.
103
+
104
+ An API key short-circuits everything. Otherwise require a prior login and use
105
+ the stored token (refreshing silently, never opening a browser).
106
+ """
107
+ key = config.api_key()
108
+ if key is not None:
109
+ return key
110
+ store = token_store()
111
+ if not store.has_tokens():
112
+ raise _AuthRequired(
113
+ "Not authenticated. Run `theirstack login`, or set "
114
+ f"{config.API_KEY_ENV} for unattended use."
115
+ )
116
+ return StoredOAuth(
117
+ mcp_url=config.mcp_url(), client_name=CLIENT_NAME, token_storage=store
118
+ )
119
+
120
+
121
+ def auth_for_login(no_browser: bool) -> OAuth:
122
+ """The OAuth provider ``theirstack login`` drives."""
123
+ cls = NoBrowserOAuth if no_browser else OAuth
124
+ return cls(
125
+ mcp_url=config.mcp_url(), client_name=CLIENT_NAME, token_storage=token_store()
126
+ )