entitybind 0.1.0__py3-none-any.whl
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.
- entitybind/__init__.py +8 -0
- entitybind/__main__.py +3 -0
- entitybind/cli.py +510 -0
- entitybind/commands_api.py +900 -0
- entitybind/commands_auth.py +393 -0
- entitybind/commands_mcp.py +236 -0
- entitybind/context.py +100 -0
- entitybind/credentials.py +349 -0
- entitybind/device.py +433 -0
- entitybind/errors.py +184 -0
- entitybind/files.py +78 -0
- entitybind/http.py +319 -0
- entitybind/mcpconfig.py +778 -0
- entitybind/products.py +126 -0
- entitybind/py.typed +0 -0
- entitybind/records.py +234 -0
- entitybind/runtime.py +163 -0
- entitybind/submissions.py +83 -0
- entitybind-0.1.0.dist-info/METADATA +251 -0
- entitybind-0.1.0.dist-info/RECORD +23 -0
- entitybind-0.1.0.dist-info/WHEEL +4 -0
- entitybind-0.1.0.dist-info/entry_points.txt +2 -0
- entitybind-0.1.0.dist-info/licenses/LICENSE +21 -0
entitybind/__init__.py
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
"""A thin command-line client for EntityBind.
|
|
2
|
+
|
|
3
|
+
It logs a person or a coding agent in, wires EntityBind into Claude Code, Codex,
|
|
4
|
+
Gemini CLI, Cursor or VS Code, and calls the Entity Bind - Core REST API. It
|
|
5
|
+
has one runtime dependency (httpx) and imports nothing from the server.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
__version__ = "0.1.0"
|
entitybind/__main__.py
ADDED
entitybind/cli.py
ADDED
|
@@ -0,0 +1,510 @@
|
|
|
1
|
+
"""The `entitybind` command line.
|
|
2
|
+
|
|
3
|
+
Run `entitybind --help` or `entitybind <command> --help`. Every command takes
|
|
4
|
+
--json for machine output and exits with a stable code (see EXIT CODES).
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import argparse
|
|
10
|
+
import contextlib
|
|
11
|
+
import sys
|
|
12
|
+
from collections.abc import Callable, Sequence
|
|
13
|
+
from datetime import date
|
|
14
|
+
from typing import NoReturn
|
|
15
|
+
|
|
16
|
+
from entitybind import __version__
|
|
17
|
+
from entitybind.commands_api import (
|
|
18
|
+
cmd_billing_checkout,
|
|
19
|
+
cmd_billing_status,
|
|
20
|
+
cmd_decisions_get,
|
|
21
|
+
cmd_discover,
|
|
22
|
+
cmd_jobs_cancel,
|
|
23
|
+
cmd_jobs_get,
|
|
24
|
+
cmd_jobs_list,
|
|
25
|
+
cmd_jobs_results,
|
|
26
|
+
cmd_jobs_submit,
|
|
27
|
+
cmd_jobs_wait,
|
|
28
|
+
cmd_keys_create,
|
|
29
|
+
cmd_keys_list,
|
|
30
|
+
cmd_keys_revoke,
|
|
31
|
+
cmd_keys_rotate,
|
|
32
|
+
cmd_quote,
|
|
33
|
+
cmd_resolve,
|
|
34
|
+
cmd_usage,
|
|
35
|
+
)
|
|
36
|
+
from entitybind.commands_auth import CORE_LOGIN_SCOPES, cmd_login, cmd_logout, cmd_whoami
|
|
37
|
+
from entitybind.commands_mcp import cmd_mcp_add
|
|
38
|
+
from entitybind.context import Context
|
|
39
|
+
from entitybind.errors import EXIT_CODES, CliError, ConflictError, UsageError
|
|
40
|
+
from entitybind.mcpconfig import AUTH_MODES, CLIENTS, SCOPES
|
|
41
|
+
from entitybind.records import DEFAULT_CHUNK_SIZE, DEPTHS, MAPPABLE_FIELDS
|
|
42
|
+
from entitybind.runtime import Output, Runtime
|
|
43
|
+
|
|
44
|
+
Handler = Callable[[Context], int]
|
|
45
|
+
|
|
46
|
+
EXIT_CODE_HELP = "exit codes:\n" + "\n".join(
|
|
47
|
+
f" {code} {meaning}" for code, meaning in sorted(EXIT_CODES.items())
|
|
48
|
+
)
|
|
49
|
+
ENVIRONMENT_HELP = """environment:
|
|
50
|
+
ENTITYBIND_API_KEY Core key; overrides any stored credential
|
|
51
|
+
ENTITYBIND_AML_KEY AML Onboard key; overrides any stored credential
|
|
52
|
+
ENTITYBIND_ADMIN_KEY admin-scoped Core key used by `keys` commands when set
|
|
53
|
+
ENTITYBIND_BASE_URL Core base URL (default https://app.entitybind.com)
|
|
54
|
+
ENTITYBIND_AML_BASE_URL AML base URL (default https://onboard.entitybind.com)
|
|
55
|
+
ENTITYBIND_NO_KEYRING set to store credentials in the file even if keyring works
|
|
56
|
+
XDG_CONFIG_HOME credentials live in $XDG_CONFIG_HOME/entitybind (default ~/.config)
|
|
57
|
+
"""
|
|
58
|
+
ADMIN_KEY_SCOPES = ("read", "resolve", "review", "erase", "admin")
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
class _Parser(argparse.ArgumentParser):
|
|
62
|
+
def error(self, message: str) -> NoReturn:
|
|
63
|
+
raise UsageError(f"{self.prog}: {message}", hint=self.format_usage().strip())
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _number(value: str) -> float:
|
|
67
|
+
try:
|
|
68
|
+
number = float(value)
|
|
69
|
+
except ValueError:
|
|
70
|
+
raise argparse.ArgumentTypeError(f"expected a number, got {value!r}") from None
|
|
71
|
+
if number != number: # NaN
|
|
72
|
+
raise argparse.ArgumentTypeError(f"expected a number, got {value!r}")
|
|
73
|
+
return number
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def _positive_float(value: str) -> float:
|
|
77
|
+
number = _number(value)
|
|
78
|
+
if number <= 0:
|
|
79
|
+
raise argparse.ArgumentTypeError("must be greater than zero")
|
|
80
|
+
return number
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _non_negative_float(value: str) -> float:
|
|
84
|
+
number = _number(value)
|
|
85
|
+
if number < 0:
|
|
86
|
+
raise argparse.ArgumentTypeError("must be zero or more")
|
|
87
|
+
return number
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def _non_negative_int(value: str) -> int:
|
|
91
|
+
try:
|
|
92
|
+
number = int(value)
|
|
93
|
+
except ValueError:
|
|
94
|
+
raise argparse.ArgumentTypeError(f"expected a whole number, got {value!r}") from None
|
|
95
|
+
if number < 0:
|
|
96
|
+
raise argparse.ArgumentTypeError("must be zero or more")
|
|
97
|
+
return number
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _positive_int(value: str) -> int:
|
|
101
|
+
number = _non_negative_int(value)
|
|
102
|
+
if number == 0:
|
|
103
|
+
raise argparse.ArgumentTypeError("must be greater than zero")
|
|
104
|
+
return number
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _iso_date(value: str) -> str:
|
|
108
|
+
try:
|
|
109
|
+
date.fromisoformat(value)
|
|
110
|
+
except ValueError:
|
|
111
|
+
raise argparse.ArgumentTypeError(f"expected YYYY-MM-DD, got {value!r}") from None
|
|
112
|
+
return value
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _common() -> _Parser:
|
|
116
|
+
common = _Parser(add_help=False)
|
|
117
|
+
group = common.add_argument_group("common options")
|
|
118
|
+
group.add_argument(
|
|
119
|
+
"--json",
|
|
120
|
+
action="store_true",
|
|
121
|
+
default=argparse.SUPPRESS,
|
|
122
|
+
help="print machine-readable JSON on stdout (errors too)",
|
|
123
|
+
)
|
|
124
|
+
group.add_argument(
|
|
125
|
+
"--base-url",
|
|
126
|
+
metavar="URL",
|
|
127
|
+
default=argparse.SUPPRESS,
|
|
128
|
+
help="API origin (default https://app.entitybind.com, or https://onboard.entitybind.com "
|
|
129
|
+
"for --product aml)",
|
|
130
|
+
)
|
|
131
|
+
group.add_argument(
|
|
132
|
+
"--http-timeout",
|
|
133
|
+
type=_positive_float,
|
|
134
|
+
metavar="SECONDS",
|
|
135
|
+
default=argparse.SUPPRESS,
|
|
136
|
+
help="per-request timeout (default 60; 330 for a synchronous resolve)",
|
|
137
|
+
)
|
|
138
|
+
group.add_argument(
|
|
139
|
+
"--max-retries",
|
|
140
|
+
type=_non_negative_int,
|
|
141
|
+
metavar="N",
|
|
142
|
+
default=argparse.SUPPRESS,
|
|
143
|
+
help="retries on 429/503 and connection failures (default 3)",
|
|
144
|
+
)
|
|
145
|
+
return common
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def _product(parser: argparse.ArgumentParser) -> None:
|
|
149
|
+
parser.add_argument(
|
|
150
|
+
"--product",
|
|
151
|
+
choices=("core", "aml"),
|
|
152
|
+
default=argparse.SUPPRESS,
|
|
153
|
+
help="Entity Bind - Core (default) or AML Onboard",
|
|
154
|
+
)
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def _waiting(parser: argparse.ArgumentParser, default_timeout: float = 600.0) -> None:
|
|
158
|
+
parser.add_argument(
|
|
159
|
+
"--timeout",
|
|
160
|
+
type=_non_negative_float,
|
|
161
|
+
default=default_timeout,
|
|
162
|
+
metavar="SECONDS",
|
|
163
|
+
help=f"how long to wait in total before exiting 9 (default {default_timeout:g})",
|
|
164
|
+
)
|
|
165
|
+
parser.add_argument(
|
|
166
|
+
"--interval",
|
|
167
|
+
type=_positive_float,
|
|
168
|
+
default=2.0,
|
|
169
|
+
metavar="SECONDS",
|
|
170
|
+
help="first polling interval; backs off to 15s and honours Retry-After (default 2)",
|
|
171
|
+
)
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def _idempotency(parser: argparse.ArgumentParser) -> None:
|
|
175
|
+
parser.add_argument(
|
|
176
|
+
"--idempotency-key",
|
|
177
|
+
metavar="KEY",
|
|
178
|
+
help="reuse to retry safely; a fresh key is generated otherwise",
|
|
179
|
+
)
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def _record_flags(parser: argparse.ArgumentParser) -> None:
|
|
183
|
+
group = parser.add_argument_group("record")
|
|
184
|
+
group.add_argument("--name", help="company name")
|
|
185
|
+
group.add_argument("--country", help="country name or ISO code")
|
|
186
|
+
for flag in (
|
|
187
|
+
"--domain",
|
|
188
|
+
"--website",
|
|
189
|
+
"--registration-number",
|
|
190
|
+
"--jurisdiction",
|
|
191
|
+
"--lei",
|
|
192
|
+
"--vat-number",
|
|
193
|
+
"--duns",
|
|
194
|
+
"--ticker",
|
|
195
|
+
"--exchange",
|
|
196
|
+
"--email",
|
|
197
|
+
"--phone",
|
|
198
|
+
"--postcode",
|
|
199
|
+
"--city",
|
|
200
|
+
"--client-ref",
|
|
201
|
+
):
|
|
202
|
+
group.add_argument(flag)
|
|
203
|
+
group.add_argument(
|
|
204
|
+
"--context", help="what you know about the company in plain words (an unverified clue)"
|
|
205
|
+
)
|
|
206
|
+
group.add_argument(
|
|
207
|
+
"--input", metavar="FILE", help="JSON record file ('-' for stdin); flags override it"
|
|
208
|
+
)
|
|
209
|
+
parser.add_argument("--depth", choices=DEPTHS, help="price and latency ceiling per record")
|
|
210
|
+
parser.add_argument(
|
|
211
|
+
"--no-enrich", action="store_true", help="no registry lookups (dedupe against your data)"
|
|
212
|
+
)
|
|
213
|
+
parser.add_argument("--fields", metavar="A,B", help="entity attributes to return")
|
|
214
|
+
parser.add_argument(
|
|
215
|
+
"--field-pack", action="append", metavar="PACK", help="named attribute group (repeatable)"
|
|
216
|
+
)
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def _csv_flags(parser: argparse.ArgumentParser, *, key_column: bool) -> None:
|
|
220
|
+
parser.add_argument("--csv", metavar="FILE", help="CSV file with a header row")
|
|
221
|
+
parser.add_argument(
|
|
222
|
+
"--map",
|
|
223
|
+
action="append",
|
|
224
|
+
metavar="FIELD=COLUMN",
|
|
225
|
+
help="map a record field to a CSV column (repeatable, comma-separable). Columns already "
|
|
226
|
+
"named after a field map automatically. Fields: " + ", ".join(MAPPABLE_FIELDS),
|
|
227
|
+
)
|
|
228
|
+
parser.add_argument(
|
|
229
|
+
"--default-country", metavar="CC", help="country for rows that do not name one"
|
|
230
|
+
)
|
|
231
|
+
if key_column:
|
|
232
|
+
parser.add_argument(
|
|
233
|
+
"--key-column", metavar="COLUMN", help="your own row id, sent as client_ref"
|
|
234
|
+
)
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
238
|
+
common = _common()
|
|
239
|
+
parser = _Parser(
|
|
240
|
+
prog="entitybind",
|
|
241
|
+
description="Log in to EntityBind, wire it into your coding agent, and call the Core API.",
|
|
242
|
+
epilog=f"{EXIT_CODE_HELP}\n\n{ENVIRONMENT_HELP}",
|
|
243
|
+
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
244
|
+
parents=[common],
|
|
245
|
+
)
|
|
246
|
+
parser.add_argument("--version", action="version", version=f"entitybind {__version__}")
|
|
247
|
+
commands = parser.add_subparsers(dest="command", metavar="<command>", parser_class=_Parser)
|
|
248
|
+
commands.required = True
|
|
249
|
+
|
|
250
|
+
def leaf(
|
|
251
|
+
group: argparse._SubParsersAction[_Parser],
|
|
252
|
+
name: str,
|
|
253
|
+
handler: Handler,
|
|
254
|
+
help_text: str,
|
|
255
|
+
) -> argparse.ArgumentParser:
|
|
256
|
+
sub = group.add_parser(name, help=help_text, description=help_text, parents=[common])
|
|
257
|
+
sub.set_defaults(handler=handler)
|
|
258
|
+
return sub
|
|
259
|
+
|
|
260
|
+
login = leaf(commands, "login", cmd_login, "sign in with a browser approval (device flow)")
|
|
261
|
+
_product(login)
|
|
262
|
+
login.add_argument(
|
|
263
|
+
"--scope",
|
|
264
|
+
metavar="SCOPE",
|
|
265
|
+
help="Core: " + ", ".join(CORE_LOGIN_SCOPES) + " (default resolve); "
|
|
266
|
+
"AML: agent (default), partner, or AML scope names",
|
|
267
|
+
)
|
|
268
|
+
login.add_argument(
|
|
269
|
+
"--name",
|
|
270
|
+
help="suggested key label, sent with the request; current EntityBind servers ignore it "
|
|
271
|
+
"and the key is named when it is approved",
|
|
272
|
+
)
|
|
273
|
+
login.add_argument("--no-browser", action="store_true", help="print the link; do not open it")
|
|
274
|
+
login.add_argument(
|
|
275
|
+
"--print-key",
|
|
276
|
+
action="store_true",
|
|
277
|
+
help="print the key once on stdout, for a secret manager",
|
|
278
|
+
)
|
|
279
|
+
login.add_argument("--no-store", action="store_true", help="do not store the key locally")
|
|
280
|
+
login.add_argument(
|
|
281
|
+
"--timeout",
|
|
282
|
+
type=_non_negative_float,
|
|
283
|
+
metavar="SECONDS",
|
|
284
|
+
help="stop waiting after this long and exit 9; continue later with --resume",
|
|
285
|
+
)
|
|
286
|
+
login.add_argument(
|
|
287
|
+
"--no-wait", action="store_true", help="print the link and code, then exit 9 at once"
|
|
288
|
+
)
|
|
289
|
+
login.add_argument(
|
|
290
|
+
"--resume", action="store_true", help="keep waiting for a sign-in started earlier"
|
|
291
|
+
)
|
|
292
|
+
|
|
293
|
+
logout = leaf(commands, "logout", cmd_logout, "remove the stored credential")
|
|
294
|
+
_product(logout)
|
|
295
|
+
logout.add_argument(
|
|
296
|
+
"--revoke",
|
|
297
|
+
action="store_true",
|
|
298
|
+
help="revoke the key on the server first; the local record is kept unless the "
|
|
299
|
+
"revocation is confirmed",
|
|
300
|
+
)
|
|
301
|
+
logout.add_argument(
|
|
302
|
+
"--all", action="store_true", help="remove every stored credential (not with --revoke)"
|
|
303
|
+
)
|
|
304
|
+
|
|
305
|
+
whoami = leaf(commands, "whoami", cmd_whoami, "show the credential in use")
|
|
306
|
+
_product(whoami)
|
|
307
|
+
|
|
308
|
+
mcp = commands.add_parser("mcp", help="configure MCP clients")
|
|
309
|
+
mcp_commands = mcp.add_subparsers(
|
|
310
|
+
dest="mcp_command", metavar="<subcommand>", parser_class=_Parser
|
|
311
|
+
)
|
|
312
|
+
mcp_commands.required = True
|
|
313
|
+
mcp_add = leaf(mcp_commands, "add", cmd_mcp_add, "print or write an MCP client configuration")
|
|
314
|
+
mcp_add.add_argument("client", choices=CLIENTS)
|
|
315
|
+
_product(mcp_add)
|
|
316
|
+
mcp_add.add_argument(
|
|
317
|
+
"--auth",
|
|
318
|
+
choices=AUTH_MODES,
|
|
319
|
+
default="key",
|
|
320
|
+
help="key: Authorization header from an environment variable (default); oauth: URL only, "
|
|
321
|
+
"the client signs in and the workspace owner approves (Core only)",
|
|
322
|
+
)
|
|
323
|
+
mcp_add.add_argument(
|
|
324
|
+
"--scope",
|
|
325
|
+
choices=SCOPES,
|
|
326
|
+
help="project or user configuration (default: user for codex, project otherwise)",
|
|
327
|
+
)
|
|
328
|
+
mcp_add.add_argument("--write", action="store_true", help="merge the entry into the file")
|
|
329
|
+
mcp_add.add_argument(
|
|
330
|
+
"--inline-key", action="store_true", help="write the raw key into the file (not advised)"
|
|
331
|
+
)
|
|
332
|
+
mcp_add.add_argument("--server-name", metavar="NAME", help="entry name (default entitybind)")
|
|
333
|
+
mcp_add.add_argument("--dir", metavar="PATH", help="project directory (default: current)")
|
|
334
|
+
mcp_add.add_argument("--force", action="store_true", help="replace an existing entry")
|
|
335
|
+
|
|
336
|
+
resolve = leaf(commands, "resolve", cmd_resolve, "resolve one company record")
|
|
337
|
+
_record_flags(resolve)
|
|
338
|
+
resolve.add_argument(
|
|
339
|
+
"--async",
|
|
340
|
+
dest="async_",
|
|
341
|
+
action="store_true",
|
|
342
|
+
help="queue a durable job (POST /v1/resolve-jobs) instead of waiting on one request",
|
|
343
|
+
)
|
|
344
|
+
resolve.add_argument("--wait", action="store_true", help="with --async, wait for the result")
|
|
345
|
+
_waiting(resolve)
|
|
346
|
+
_idempotency(resolve)
|
|
347
|
+
|
|
348
|
+
quote = leaf(commands, "quote", cmd_quote, "estimate the credits a request would use")
|
|
349
|
+
_record_flags(quote)
|
|
350
|
+
_csv_flags(quote, key_column=False)
|
|
351
|
+
quote.add_argument(
|
|
352
|
+
"--skip-invalid",
|
|
353
|
+
action="store_true",
|
|
354
|
+
help="with --csv, leave out rows without a name or country (otherwise refused)",
|
|
355
|
+
)
|
|
356
|
+
_idempotency(quote)
|
|
357
|
+
|
|
358
|
+
discover = leaf(
|
|
359
|
+
commands, "discover", cmd_discover, "official registry candidates for a name and country"
|
|
360
|
+
)
|
|
361
|
+
discover.add_argument("--name", help="company name")
|
|
362
|
+
discover.add_argument("--country", help="country name or ISO code")
|
|
363
|
+
discover.add_argument("--website", help="optional website")
|
|
364
|
+
discover.add_argument("--input", metavar="FILE", help="JSON request file ('-' for stdin)")
|
|
365
|
+
_idempotency(discover)
|
|
366
|
+
|
|
367
|
+
jobs = commands.add_parser("jobs", help="durable batch jobs")
|
|
368
|
+
jobs_commands = jobs.add_subparsers(
|
|
369
|
+
dest="jobs_command", metavar="<subcommand>", parser_class=_Parser
|
|
370
|
+
)
|
|
371
|
+
jobs_commands.required = True
|
|
372
|
+
submit = leaf(jobs_commands, "submit", cmd_jobs_submit, "submit records as batch jobs")
|
|
373
|
+
_csv_flags(submit, key_column=True)
|
|
374
|
+
submit.add_argument(
|
|
375
|
+
"--records", metavar="FILE", help="JSON list, {records: [...]} or JSON lines"
|
|
376
|
+
)
|
|
377
|
+
submit.add_argument("--depth", choices=DEPTHS, help="depth for records that do not set one")
|
|
378
|
+
submit.add_argument(
|
|
379
|
+
"--chunk-size",
|
|
380
|
+
type=_positive_int,
|
|
381
|
+
default=DEFAULT_CHUNK_SIZE,
|
|
382
|
+
metavar="N",
|
|
383
|
+
help=f"records per job (default {DEFAULT_CHUNK_SIZE}, Core's default batch limit; "
|
|
384
|
+
"GET /v1/reference/limits shows a deployment's max_batch_size)",
|
|
385
|
+
)
|
|
386
|
+
submit.add_argument(
|
|
387
|
+
"--skip-invalid", action="store_true", help="skip rows without a name or country"
|
|
388
|
+
)
|
|
389
|
+
submit.add_argument("--wait", action="store_true", help="wait for every job to finish")
|
|
390
|
+
_waiting(submit)
|
|
391
|
+
_idempotency(submit)
|
|
392
|
+
jobs_list = leaf(jobs_commands, "list", cmd_jobs_list, "list your batch jobs")
|
|
393
|
+
jobs_list.add_argument("--limit", type=_positive_int, metavar="N")
|
|
394
|
+
jobs_list.add_argument("--cursor", metavar="CURSOR")
|
|
395
|
+
jobs_list.add_argument("--state", metavar="STATE")
|
|
396
|
+
jobs_get = leaf(jobs_commands, "get", cmd_jobs_get, "show one job")
|
|
397
|
+
jobs_get.add_argument("job_id")
|
|
398
|
+
jobs_wait = leaf(jobs_commands, "wait", cmd_jobs_wait, "wait until a job finishes")
|
|
399
|
+
jobs_wait.add_argument("job_id")
|
|
400
|
+
_waiting(jobs_wait)
|
|
401
|
+
jobs_results = leaf(jobs_commands, "results", cmd_jobs_results, "print or save a job's results")
|
|
402
|
+
jobs_results.add_argument("job_id")
|
|
403
|
+
jobs_results.add_argument("--format", choices=("json", "csv"), default="json")
|
|
404
|
+
jobs_results.add_argument("--output", metavar="FILE", help="write to a file (mode 600)")
|
|
405
|
+
jobs_results.add_argument("--wait", action="store_true", help="wait for the job first")
|
|
406
|
+
_waiting(jobs_results)
|
|
407
|
+
jobs_cancel = leaf(jobs_commands, "cancel", cmd_jobs_cancel, "cancel a queued job")
|
|
408
|
+
jobs_cancel.add_argument("job_id")
|
|
409
|
+
|
|
410
|
+
usage = leaf(commands, "usage", cmd_usage, "calls, credits and rates for a period")
|
|
411
|
+
usage.add_argument("--since", type=_iso_date, metavar="YYYY-MM-DD")
|
|
412
|
+
usage.add_argument("--until", type=_iso_date, metavar="YYYY-MM-DD")
|
|
413
|
+
|
|
414
|
+
billing = commands.add_parser("billing", help="plan and payment")
|
|
415
|
+
billing_commands = billing.add_subparsers(
|
|
416
|
+
dest="billing_command", metavar="<subcommand>", parser_class=_Parser
|
|
417
|
+
)
|
|
418
|
+
billing_commands.required = True
|
|
419
|
+
leaf(billing_commands, "status", cmd_billing_status, "plan, credits and payment state")
|
|
420
|
+
checkout = leaf(
|
|
421
|
+
billing_commands, "checkout", cmd_billing_checkout, "a checkout link for a person to pay"
|
|
422
|
+
)
|
|
423
|
+
checkout.add_argument("--plan", required=True, help="plan to buy, e.g. starter")
|
|
424
|
+
checkout.add_argument("--open", action="store_true", help="open the link in a browser")
|
|
425
|
+
_idempotency(checkout)
|
|
426
|
+
|
|
427
|
+
keys = commands.add_parser("keys", help="manage API keys (admin-scoped key)")
|
|
428
|
+
keys_commands = keys.add_subparsers(
|
|
429
|
+
dest="keys_command", metavar="<subcommand>", parser_class=_Parser
|
|
430
|
+
)
|
|
431
|
+
keys_commands.required = True
|
|
432
|
+
keys_list = leaf(keys_commands, "list", cmd_keys_list, "list a workspace's keys")
|
|
433
|
+
keys_list.add_argument("--tenant-id", metavar="ID", help="default: your own workspace")
|
|
434
|
+
keys_create = leaf(keys_commands, "create", cmd_keys_create, "create a key (shown once)")
|
|
435
|
+
keys_create.add_argument("--name", required=True, help="label for the key")
|
|
436
|
+
keys_create.add_argument("--scope", choices=ADMIN_KEY_SCOPES, default="resolve")
|
|
437
|
+
keys_create.add_argument("--plan", help="plan, capped at the workspace's own plan")
|
|
438
|
+
keys_create.add_argument("--tenant-id", metavar="ID", help="default: your own workspace")
|
|
439
|
+
keys_create.add_argument(
|
|
440
|
+
"--expires-in", metavar="DURATION", help="one hour to one year, e.g. 3600, 90m, 12h, 30d"
|
|
441
|
+
)
|
|
442
|
+
keys_create.add_argument(
|
|
443
|
+
"--expires-at", metavar="TIME", help="ISO 8601, e.g. 2027-01-31T00:00:00Z"
|
|
444
|
+
)
|
|
445
|
+
keys_create.add_argument(
|
|
446
|
+
"--credit-limit", type=int, metavar="N", help="credits this key may spend"
|
|
447
|
+
)
|
|
448
|
+
keys_create.add_argument(
|
|
449
|
+
"--max-depth", choices=DEPTHS, help="deepest resolution this key may run"
|
|
450
|
+
)
|
|
451
|
+
# No --idempotency-key: the admin key routes do not honour one, so a retry
|
|
452
|
+
# after a timeout could mint a second key whatever key was sent.
|
|
453
|
+
keys_rotate = leaf(
|
|
454
|
+
keys_commands, "rotate", cmd_keys_rotate, "replace a key (new key shown once)"
|
|
455
|
+
)
|
|
456
|
+
keys_rotate.add_argument("key_id")
|
|
457
|
+
keys_rotate.add_argument(
|
|
458
|
+
"--grace-seconds", type=int, metavar="N", help="old key keeps working this long (0: now)"
|
|
459
|
+
)
|
|
460
|
+
keys_revoke = leaf(keys_commands, "revoke", cmd_keys_revoke, "revoke a key immediately")
|
|
461
|
+
keys_revoke.add_argument("key_id")
|
|
462
|
+
|
|
463
|
+
decisions = commands.add_parser("decisions", help="decision receipts")
|
|
464
|
+
decisions_commands = decisions.add_subparsers(
|
|
465
|
+
dest="decisions_command", metavar="<subcommand>", parser_class=_Parser
|
|
466
|
+
)
|
|
467
|
+
decisions_commands.required = True
|
|
468
|
+
decisions_get = leaf(decisions_commands, "get", cmd_decisions_get, "show one decision receipt")
|
|
469
|
+
decisions_get.add_argument("decision_id")
|
|
470
|
+
return parser
|
|
471
|
+
|
|
472
|
+
|
|
473
|
+
def main(argv: Sequence[str] | None = None, runtime: Runtime | None = None) -> int:
|
|
474
|
+
runtime = runtime or Runtime.system()
|
|
475
|
+
arguments = list(sys.argv[1:] if argv is None else argv)
|
|
476
|
+
parser = build_parser()
|
|
477
|
+
try:
|
|
478
|
+
with contextlib.redirect_stdout(runtime.stdout), contextlib.redirect_stderr(runtime.stderr):
|
|
479
|
+
args = parser.parse_args(arguments)
|
|
480
|
+
except UsageError as error:
|
|
481
|
+
Output(runtime, json_mode="--json" in arguments).error(error)
|
|
482
|
+
return error.exit_code
|
|
483
|
+
except SystemExit as stop: # --help and --version
|
|
484
|
+
return stop.code if isinstance(stop.code, int) else 0
|
|
485
|
+
context = Context(runtime, args)
|
|
486
|
+
handler: Handler = args.handler
|
|
487
|
+
try:
|
|
488
|
+
return int(handler(context))
|
|
489
|
+
except CliError as error:
|
|
490
|
+
context.output.error(error)
|
|
491
|
+
return error.exit_code
|
|
492
|
+
except KeyboardInterrupt:
|
|
493
|
+
context.output.info("interrupted")
|
|
494
|
+
return 130
|
|
495
|
+
except (OSError, UnicodeDecodeError) as exc:
|
|
496
|
+
failure = local_failure(exc)
|
|
497
|
+
context.output.error(failure)
|
|
498
|
+
return failure.exit_code
|
|
499
|
+
|
|
500
|
+
|
|
501
|
+
def local_failure(exc: OSError | UnicodeDecodeError) -> CliError:
|
|
502
|
+
"""A local file failure no command anticipated, kept to the published exit codes."""
|
|
503
|
+
if isinstance(exc, UnicodeDecodeError):
|
|
504
|
+
return ConflictError(f"a file is not UTF-8 text ({exc.reason})", code="file_error")
|
|
505
|
+
where = f": {exc.filename}" if exc.filename else ""
|
|
506
|
+
return ConflictError(f"{exc.strerror or type(exc).__name__}{where}", code="file_error")
|
|
507
|
+
|
|
508
|
+
|
|
509
|
+
if __name__ == "__main__": # pragma: no cover
|
|
510
|
+
raise SystemExit(main())
|