entitybind 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.
- entitybind-0.1.0/.gitignore +11 -0
- entitybind-0.1.0/LICENSE +21 -0
- entitybind-0.1.0/PKG-INFO +251 -0
- entitybind-0.1.0/README.md +222 -0
- entitybind-0.1.0/pyproject.toml +96 -0
- entitybind-0.1.0/src/entitybind/__init__.py +8 -0
- entitybind-0.1.0/src/entitybind/__main__.py +3 -0
- entitybind-0.1.0/src/entitybind/cli.py +510 -0
- entitybind-0.1.0/src/entitybind/commands_api.py +900 -0
- entitybind-0.1.0/src/entitybind/commands_auth.py +393 -0
- entitybind-0.1.0/src/entitybind/commands_mcp.py +236 -0
- entitybind-0.1.0/src/entitybind/context.py +100 -0
- entitybind-0.1.0/src/entitybind/credentials.py +349 -0
- entitybind-0.1.0/src/entitybind/device.py +433 -0
- entitybind-0.1.0/src/entitybind/errors.py +184 -0
- entitybind-0.1.0/src/entitybind/files.py +78 -0
- entitybind-0.1.0/src/entitybind/http.py +319 -0
- entitybind-0.1.0/src/entitybind/mcpconfig.py +778 -0
- entitybind-0.1.0/src/entitybind/products.py +126 -0
- entitybind-0.1.0/src/entitybind/py.typed +0 -0
- entitybind-0.1.0/src/entitybind/records.py +234 -0
- entitybind-0.1.0/src/entitybind/runtime.py +163 -0
- entitybind-0.1.0/src/entitybind/submissions.py +83 -0
- entitybind-0.1.0/tests/conftest.py +246 -0
- entitybind-0.1.0/tests/test_api_commands.py +1111 -0
- entitybind-0.1.0/tests/test_auth_commands.py +348 -0
- entitybind-0.1.0/tests/test_credentials.py +333 -0
- entitybind-0.1.0/tests/test_http.py +318 -0
- entitybind-0.1.0/tests/test_login.py +454 -0
- entitybind-0.1.0/tests/test_mcp_add.py +761 -0
- entitybind-0.1.0/tests/test_products.py +43 -0
- entitybind-0.1.0/tests/test_records.py +119 -0
- entitybind-0.1.0/tests/test_registry_entries.py +62 -0
- entitybind-0.1.0/tests/test_runtime.py +78 -0
entitybind-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tenhaw
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: entitybind
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: EntityBind command-line client: log in, wire EntityBind into Claude Code, Codex, Gemini CLI, Cursor or VS Code, and call the Core API.
|
|
5
|
+
Project-URL: Homepage, https://app.entitybind.com
|
|
6
|
+
Project-URL: Documentation, https://app.entitybind.com/api/docs
|
|
7
|
+
Project-URL: Source, https://github.com/Tenhaw/entity-resolution/tree/main/clients/python
|
|
8
|
+
Author: EntityBind
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: cli,company-data,entity-resolution,entitybind,kyc,mcp
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Utilities
|
|
23
|
+
Classifier: Typing :: Typed
|
|
24
|
+
Requires-Python: >=3.10
|
|
25
|
+
Requires-Dist: httpx<1,>=0.27
|
|
26
|
+
Provides-Extra: keyring
|
|
27
|
+
Requires-Dist: keyring>=24; extra == 'keyring'
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# entitybind
|
|
31
|
+
|
|
32
|
+
The command-line client for [EntityBind](https://app.entitybind.com). It signs
|
|
33
|
+
a person or a coding agent in, wires EntityBind's MCP servers into Claude Code,
|
|
34
|
+
Codex, Gemini CLI, Cursor or VS Code, and calls the Entity Bind - Core API:
|
|
35
|
+
resolve, quote, registry discovery, batch jobs, usage, billing, keys and
|
|
36
|
+
decision receipts.
|
|
37
|
+
|
|
38
|
+
It has one runtime dependency (`httpx`), needs Python 3.10 or later, and talks
|
|
39
|
+
only to the EntityBind origins you point it at.
|
|
40
|
+
|
|
41
|
+
## Install
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
uvx entitybind --help # run without installing
|
|
45
|
+
pipx install entitybind # or install it as a tool
|
|
46
|
+
pipx install 'entitybind[keyring]' # store credentials in the OS keyring
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The npm package of the same name provides `login`, `logout`, `whoami` and
|
|
50
|
+
`mcp add` for machines without Python: `npx entitybind login`.
|
|
51
|
+
|
|
52
|
+
## Sign in
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
entitybind login # Entity Bind - Core
|
|
56
|
+
entitybind login --product aml # AML Onboard
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`login` uses the OAuth device flow (RFC 8628). It prints a link and a short
|
|
60
|
+
code, opens your browser, and waits while you approve the request as the
|
|
61
|
+
workspace owner. The resulting key is stored:
|
|
62
|
+
|
|
63
|
+
- in the OS keyring, when `entitybind[keyring]` is installed and a keyring
|
|
64
|
+
backend works; otherwise
|
|
65
|
+
- in `$XDG_CONFIG_HOME/entitybind/credentials.json` (default `~/.config`),
|
|
66
|
+
mode 0600 in a 0700 directory.
|
|
67
|
+
|
|
68
|
+
Credentials are kept per product and base URL. `entitybind whoami` shows which
|
|
69
|
+
credential is in use; `entitybind logout` removes it. `--revoke` revokes the
|
|
70
|
+
key on the server first and removes the local copy only once the server
|
|
71
|
+
confirms the key no longer works; otherwise it exits non-zero
|
|
72
|
+
(`revocation_unconfirmed`), keeps the local copy and names the key id.
|
|
73
|
+
|
|
74
|
+
AML device login is for sandbox workspaces and needs an MFA administrator's
|
|
75
|
+
approval. In a self-serve workspace it reports `simulated_checks_only: true`
|
|
76
|
+
in JSON and explains that checks use synthetic providers only.
|
|
77
|
+
|
|
78
|
+
Useful options: `--scope` (Core: `read`, `resolve`, `review` or `admin`,
|
|
79
|
+
default `resolve`; AML: `agent`, the default, `partner`, or AML scope names),
|
|
80
|
+
`--name` (a suggested key label; current servers ignore it and the key is
|
|
81
|
+
named when it is approved), `--no-browser`, `--print-key` (print the key
|
|
82
|
+
once on stdout, for a secret manager), and `--no-store` (only with
|
|
83
|
+
`--print-key`, so the key is never discarded). The browser is opened only for
|
|
84
|
+
an `https` link.
|
|
85
|
+
|
|
86
|
+
### Signing in from a coding agent
|
|
87
|
+
|
|
88
|
+
An agent's tool call may time out before a person approves. Use a time limit
|
|
89
|
+
and resume:
|
|
90
|
+
|
|
91
|
+
```sh
|
|
92
|
+
entitybind login --no-browser --timeout 50 --json # exits 9 while waiting
|
|
93
|
+
entitybind login --resume --timeout 50 --json # repeat until it exits 0
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
With `--json`, the link and code are printed on stderr as a JSON event for the
|
|
97
|
+
agent to relay to the person; stdout carries one JSON result. A started sign-in
|
|
98
|
+
is saved (mode 0600) until it is approved, denied or expires.
|
|
99
|
+
|
|
100
|
+
## Wire EntityBind into your agent
|
|
101
|
+
|
|
102
|
+
```sh
|
|
103
|
+
entitybind mcp add claude-code # print the entry for ./.mcp.json
|
|
104
|
+
entitybind mcp add claude-code --write # merge it into ./.mcp.json
|
|
105
|
+
entitybind mcp add codex --write # ~/.codex/config.toml
|
|
106
|
+
entitybind mcp add gemini --write # ./.gemini/settings.json
|
|
107
|
+
entitybind mcp add cursor --write # ./.cursor/mcp.json
|
|
108
|
+
entitybind mcp add vscode --write # ./.vscode/mcp.json
|
|
109
|
+
entitybind mcp add claude-code --product aml --write
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`--auth key` (the default) sends `Authorization: Bearer` with the key taken
|
|
113
|
+
from an environment variable, `ENTITYBIND_API_KEY` for Core or
|
|
114
|
+
`ENTITYBIND_AML_KEY` for AML, so no key is written to disk. A plain `login`
|
|
115
|
+
never prints the stored key, so get one for the agent with `--print-key`, and
|
|
116
|
+
set the variable for that agent's process or project only, not in your shell
|
|
117
|
+
profile:
|
|
118
|
+
|
|
119
|
+
```sh
|
|
120
|
+
export ENTITYBIND_API_KEY="$(entitybind login --print-key --no-store)" # this shell only
|
|
121
|
+
claude
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Headless agents such as `claude -p` load a repository's committed `.mcp.json`
|
|
125
|
+
without asking, so a hostile repository could name the same variable for its
|
|
126
|
+
own server and receive an exported key. `--inline-key` writes the raw key instead (with a
|
|
127
|
+
warning, mode 0600), and only into a user-scope file: it is refused for
|
|
128
|
+
project files such as `./.mcp.json`, which are usually committed, so add
|
|
129
|
+
`--scope user`.
|
|
130
|
+
|
|
131
|
+
`--auth oauth` (Core only) configures just the URL. The client registers
|
|
132
|
+
itself and the workspace owner approves the connection in the browser: run
|
|
133
|
+
`/mcp` in Claude Code, `codex mcp login entitybind`, or `/mcp auth entitybind`
|
|
134
|
+
in Gemini CLI.
|
|
135
|
+
|
|
136
|
+
Other options: `--scope project|user` (Codex defaults to `user`, the others to
|
|
137
|
+
`project`), `--dir`, `--server-name`, and `--force` to update the URL and
|
|
138
|
+
credential settings of an existing entry of the same name. Settings you added
|
|
139
|
+
to the entry yourself (timeouts, trust, tool filters, Codex approval modes)
|
|
140
|
+
are never a conflict and are kept, with or without `--force`. Merging keeps everything else in the file, writes
|
|
141
|
+
atomically, and refuses files it cannot rewrite safely (for example JSON with
|
|
142
|
+
comments) rather than reformatting them. Claude Code's user scope is written by
|
|
143
|
+
running `claude mcp add-json` for you.
|
|
144
|
+
|
|
145
|
+
Gemini CLI blanks environment variables whose names contain `KEY` when it
|
|
146
|
+
expands headers, so `mcp add gemini` also adds the variable to
|
|
147
|
+
`security.environmentVariableRedaction.allowed`.
|
|
148
|
+
With `--json`, the `configuration` field contains the complete JSON fragment,
|
|
149
|
+
including that allowlist, for an agent to apply.
|
|
150
|
+
|
|
151
|
+
## Use the Core API
|
|
152
|
+
|
|
153
|
+
```sh
|
|
154
|
+
entitybind resolve --name "Acme Ltd" --country GB --postcode "SW1A 1AA"
|
|
155
|
+
entitybind resolve --input record.json --async --wait --json
|
|
156
|
+
entitybind quote --csv suppliers.csv --map name="Company Name" --default-country GB
|
|
157
|
+
entitybind discover --name "Acme" --country GB
|
|
158
|
+
entitybind jobs submit --csv suppliers.csv --map name="Company Name" \
|
|
159
|
+
--key-column "Supplier ID" --default-country GB --wait
|
|
160
|
+
entitybind jobs list
|
|
161
|
+
entitybind jobs results job_... --format csv --output results.csv
|
|
162
|
+
entitybind usage --since 2026-11-01
|
|
163
|
+
entitybind billing status
|
|
164
|
+
entitybind billing checkout --plan starter # prints a link for a person to pay
|
|
165
|
+
entitybind keys create --name ci --scope resolve --expires-in 30d # admin key
|
|
166
|
+
entitybind decisions get dec_...
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
`jobs submit` maps CSV columns the same way as the repository's
|
|
170
|
+
`resolvd import-csv`: `--map field=Column` (repeatable, comma-separable), and
|
|
171
|
+
columns already named after a field map automatically. Rows without a name or
|
|
172
|
+
country are refused unless you pass `--skip-invalid` (in `quote --csv` too, so
|
|
173
|
+
a quote never silently covers fewer rows than the file). Large files are split
|
|
174
|
+
into jobs of `--chunk-size` records (default 500, Core's default batch limit;
|
|
175
|
+
`GET /v1/reference/limits` reports a deployment's `max_batch_size`). A
|
|
176
|
+
workspace may have only a limited number of jobs pending at once (ten by
|
|
177
|
+
default), so very large files may need `--wait` between runs.
|
|
178
|
+
|
|
179
|
+
`keys` commands need an admin-scoped key. Core scopes do not overlap, so keep
|
|
180
|
+
your everyday key stored and pass an admin key through the environment for key
|
|
181
|
+
management:
|
|
182
|
+
|
|
183
|
+
```sh
|
|
184
|
+
export ENTITYBIND_ADMIN_KEY="$(entitybind login --scope admin --print-key --no-store)"
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Signing in with a different scope would replace the stored key and leave it
|
|
188
|
+
active, so `login` refuses that (`scope_change`) until you run
|
|
189
|
+
`entitybind logout --revoke`. Signing in again with the same scope replaces the
|
|
190
|
+
stored key and names the key it replaced, which stays active until it expires
|
|
191
|
+
or is revoked.
|
|
192
|
+
|
|
193
|
+
## Non-interactive use (CI)
|
|
194
|
+
|
|
195
|
+
Create a key once, keep it in your secret store, and pass it through the
|
|
196
|
+
environment. Nothing is stored on the runner.
|
|
197
|
+
|
|
198
|
+
```sh
|
|
199
|
+
entitybind login --scope resolve --print-key --no-store | your-secret-manager put entitybind
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
```yaml
|
|
203
|
+
- run: uvx entitybind@0.1.0 resolve --name "Acme Ltd" --country GB --json
|
|
204
|
+
env:
|
|
205
|
+
ENTITYBIND_API_KEY: ${{ secrets.ENTITYBIND_API_KEY }}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
Pin the version in automation (`uvx entitybind@0.1.0`), so CI never runs a
|
|
209
|
+
release, or anything published under the name, that nobody reviewed.
|
|
210
|
+
`ENTITYBIND_API_KEY` and `ENTITYBIND_AML_KEY` override any stored credential.
|
|
211
|
+
`ENTITYBIND_BASE_URL` and `ENTITYBIND_AML_BASE_URL` (or `--base-url`) point the
|
|
212
|
+
client elsewhere; plain `http` is accepted only for `localhost`.
|
|
213
|
+
|
|
214
|
+
## Output and exit codes
|
|
215
|
+
|
|
216
|
+
Every command accepts `--json`. Successful API commands print the server's
|
|
217
|
+
JSON body; errors print `{"error": {...}, "status": ..., "exit_code": ...}` on
|
|
218
|
+
stdout, including any `remediation` the server returned. Progress goes to
|
|
219
|
+
stderr.
|
|
220
|
+
|
|
221
|
+
| Code | Meaning |
|
|
222
|
+
|---:|---|
|
|
223
|
+
| 0 | ok |
|
|
224
|
+
| 2 | usage error or invalid request |
|
|
225
|
+
| 3 | authentication or permission |
|
|
226
|
+
| 4 | payment or entitlement |
|
|
227
|
+
| 5 | not found |
|
|
228
|
+
| 6 | conflict |
|
|
229
|
+
| 7 | rate limited |
|
|
230
|
+
| 8 | server or network error |
|
|
231
|
+
| 9 | still pending or timed out |
|
|
232
|
+
|
|
233
|
+
`jobs wait` exits 0 for `succeeded`, 8 for `failed` or
|
|
234
|
+
`reconciliation_required`, 6 for `cancelled` and 5 for `erased`.
|
|
235
|
+
|
|
236
|
+
Requests carry `User-Agent: entitybind-cli/<version>` and
|
|
237
|
+
`X-EntityBind-Client: cli`. Mutating requests carry an `Idempotency-Key`
|
|
238
|
+
(pass `--idempotency-key` to choose it), and an error names the key it was
|
|
239
|
+
sent with; 429 and 503 responses are retried after the server's
|
|
240
|
+
`Retry-After`.
|
|
241
|
+
|
|
242
|
+
If `jobs submit` stops part-way (for example at the workspace's limit on
|
|
243
|
+
pending jobs), the error lists the jobs already accepted. Rerunning the same
|
|
244
|
+
command within 24 hours resumes the submission: it reuses the remembered
|
|
245
|
+
idempotency key, so the accepted jobs are recovered rather than queued again.
|
|
246
|
+
`--timeout` covers the whole `--wait`, and a passing 5xx or network failure
|
|
247
|
+
while waiting does not end it.
|
|
248
|
+
|
|
249
|
+
## Licence
|
|
250
|
+
|
|
251
|
+
MIT.
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
# entitybind
|
|
2
|
+
|
|
3
|
+
The command-line client for [EntityBind](https://app.entitybind.com). It signs
|
|
4
|
+
a person or a coding agent in, wires EntityBind's MCP servers into Claude Code,
|
|
5
|
+
Codex, Gemini CLI, Cursor or VS Code, and calls the Entity Bind - Core API:
|
|
6
|
+
resolve, quote, registry discovery, batch jobs, usage, billing, keys and
|
|
7
|
+
decision receipts.
|
|
8
|
+
|
|
9
|
+
It has one runtime dependency (`httpx`), needs Python 3.10 or later, and talks
|
|
10
|
+
only to the EntityBind origins you point it at.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
uvx entitybind --help # run without installing
|
|
16
|
+
pipx install entitybind # or install it as a tool
|
|
17
|
+
pipx install 'entitybind[keyring]' # store credentials in the OS keyring
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The npm package of the same name provides `login`, `logout`, `whoami` and
|
|
21
|
+
`mcp add` for machines without Python: `npx entitybind login`.
|
|
22
|
+
|
|
23
|
+
## Sign in
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
entitybind login # Entity Bind - Core
|
|
27
|
+
entitybind login --product aml # AML Onboard
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`login` uses the OAuth device flow (RFC 8628). It prints a link and a short
|
|
31
|
+
code, opens your browser, and waits while you approve the request as the
|
|
32
|
+
workspace owner. The resulting key is stored:
|
|
33
|
+
|
|
34
|
+
- in the OS keyring, when `entitybind[keyring]` is installed and a keyring
|
|
35
|
+
backend works; otherwise
|
|
36
|
+
- in `$XDG_CONFIG_HOME/entitybind/credentials.json` (default `~/.config`),
|
|
37
|
+
mode 0600 in a 0700 directory.
|
|
38
|
+
|
|
39
|
+
Credentials are kept per product and base URL. `entitybind whoami` shows which
|
|
40
|
+
credential is in use; `entitybind logout` removes it. `--revoke` revokes the
|
|
41
|
+
key on the server first and removes the local copy only once the server
|
|
42
|
+
confirms the key no longer works; otherwise it exits non-zero
|
|
43
|
+
(`revocation_unconfirmed`), keeps the local copy and names the key id.
|
|
44
|
+
|
|
45
|
+
AML device login is for sandbox workspaces and needs an MFA administrator's
|
|
46
|
+
approval. In a self-serve workspace it reports `simulated_checks_only: true`
|
|
47
|
+
in JSON and explains that checks use synthetic providers only.
|
|
48
|
+
|
|
49
|
+
Useful options: `--scope` (Core: `read`, `resolve`, `review` or `admin`,
|
|
50
|
+
default `resolve`; AML: `agent`, the default, `partner`, or AML scope names),
|
|
51
|
+
`--name` (a suggested key label; current servers ignore it and the key is
|
|
52
|
+
named when it is approved), `--no-browser`, `--print-key` (print the key
|
|
53
|
+
once on stdout, for a secret manager), and `--no-store` (only with
|
|
54
|
+
`--print-key`, so the key is never discarded). The browser is opened only for
|
|
55
|
+
an `https` link.
|
|
56
|
+
|
|
57
|
+
### Signing in from a coding agent
|
|
58
|
+
|
|
59
|
+
An agent's tool call may time out before a person approves. Use a time limit
|
|
60
|
+
and resume:
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
entitybind login --no-browser --timeout 50 --json # exits 9 while waiting
|
|
64
|
+
entitybind login --resume --timeout 50 --json # repeat until it exits 0
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
With `--json`, the link and code are printed on stderr as a JSON event for the
|
|
68
|
+
agent to relay to the person; stdout carries one JSON result. A started sign-in
|
|
69
|
+
is saved (mode 0600) until it is approved, denied or expires.
|
|
70
|
+
|
|
71
|
+
## Wire EntityBind into your agent
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
entitybind mcp add claude-code # print the entry for ./.mcp.json
|
|
75
|
+
entitybind mcp add claude-code --write # merge it into ./.mcp.json
|
|
76
|
+
entitybind mcp add codex --write # ~/.codex/config.toml
|
|
77
|
+
entitybind mcp add gemini --write # ./.gemini/settings.json
|
|
78
|
+
entitybind mcp add cursor --write # ./.cursor/mcp.json
|
|
79
|
+
entitybind mcp add vscode --write # ./.vscode/mcp.json
|
|
80
|
+
entitybind mcp add claude-code --product aml --write
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`--auth key` (the default) sends `Authorization: Bearer` with the key taken
|
|
84
|
+
from an environment variable, `ENTITYBIND_API_KEY` for Core or
|
|
85
|
+
`ENTITYBIND_AML_KEY` for AML, so no key is written to disk. A plain `login`
|
|
86
|
+
never prints the stored key, so get one for the agent with `--print-key`, and
|
|
87
|
+
set the variable for that agent's process or project only, not in your shell
|
|
88
|
+
profile:
|
|
89
|
+
|
|
90
|
+
```sh
|
|
91
|
+
export ENTITYBIND_API_KEY="$(entitybind login --print-key --no-store)" # this shell only
|
|
92
|
+
claude
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Headless agents such as `claude -p` load a repository's committed `.mcp.json`
|
|
96
|
+
without asking, so a hostile repository could name the same variable for its
|
|
97
|
+
own server and receive an exported key. `--inline-key` writes the raw key instead (with a
|
|
98
|
+
warning, mode 0600), and only into a user-scope file: it is refused for
|
|
99
|
+
project files such as `./.mcp.json`, which are usually committed, so add
|
|
100
|
+
`--scope user`.
|
|
101
|
+
|
|
102
|
+
`--auth oauth` (Core only) configures just the URL. The client registers
|
|
103
|
+
itself and the workspace owner approves the connection in the browser: run
|
|
104
|
+
`/mcp` in Claude Code, `codex mcp login entitybind`, or `/mcp auth entitybind`
|
|
105
|
+
in Gemini CLI.
|
|
106
|
+
|
|
107
|
+
Other options: `--scope project|user` (Codex defaults to `user`, the others to
|
|
108
|
+
`project`), `--dir`, `--server-name`, and `--force` to update the URL and
|
|
109
|
+
credential settings of an existing entry of the same name. Settings you added
|
|
110
|
+
to the entry yourself (timeouts, trust, tool filters, Codex approval modes)
|
|
111
|
+
are never a conflict and are kept, with or without `--force`. Merging keeps everything else in the file, writes
|
|
112
|
+
atomically, and refuses files it cannot rewrite safely (for example JSON with
|
|
113
|
+
comments) rather than reformatting them. Claude Code's user scope is written by
|
|
114
|
+
running `claude mcp add-json` for you.
|
|
115
|
+
|
|
116
|
+
Gemini CLI blanks environment variables whose names contain `KEY` when it
|
|
117
|
+
expands headers, so `mcp add gemini` also adds the variable to
|
|
118
|
+
`security.environmentVariableRedaction.allowed`.
|
|
119
|
+
With `--json`, the `configuration` field contains the complete JSON fragment,
|
|
120
|
+
including that allowlist, for an agent to apply.
|
|
121
|
+
|
|
122
|
+
## Use the Core API
|
|
123
|
+
|
|
124
|
+
```sh
|
|
125
|
+
entitybind resolve --name "Acme Ltd" --country GB --postcode "SW1A 1AA"
|
|
126
|
+
entitybind resolve --input record.json --async --wait --json
|
|
127
|
+
entitybind quote --csv suppliers.csv --map name="Company Name" --default-country GB
|
|
128
|
+
entitybind discover --name "Acme" --country GB
|
|
129
|
+
entitybind jobs submit --csv suppliers.csv --map name="Company Name" \
|
|
130
|
+
--key-column "Supplier ID" --default-country GB --wait
|
|
131
|
+
entitybind jobs list
|
|
132
|
+
entitybind jobs results job_... --format csv --output results.csv
|
|
133
|
+
entitybind usage --since 2026-11-01
|
|
134
|
+
entitybind billing status
|
|
135
|
+
entitybind billing checkout --plan starter # prints a link for a person to pay
|
|
136
|
+
entitybind keys create --name ci --scope resolve --expires-in 30d # admin key
|
|
137
|
+
entitybind decisions get dec_...
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
`jobs submit` maps CSV columns the same way as the repository's
|
|
141
|
+
`resolvd import-csv`: `--map field=Column` (repeatable, comma-separable), and
|
|
142
|
+
columns already named after a field map automatically. Rows without a name or
|
|
143
|
+
country are refused unless you pass `--skip-invalid` (in `quote --csv` too, so
|
|
144
|
+
a quote never silently covers fewer rows than the file). Large files are split
|
|
145
|
+
into jobs of `--chunk-size` records (default 500, Core's default batch limit;
|
|
146
|
+
`GET /v1/reference/limits` reports a deployment's `max_batch_size`). A
|
|
147
|
+
workspace may have only a limited number of jobs pending at once (ten by
|
|
148
|
+
default), so very large files may need `--wait` between runs.
|
|
149
|
+
|
|
150
|
+
`keys` commands need an admin-scoped key. Core scopes do not overlap, so keep
|
|
151
|
+
your everyday key stored and pass an admin key through the environment for key
|
|
152
|
+
management:
|
|
153
|
+
|
|
154
|
+
```sh
|
|
155
|
+
export ENTITYBIND_ADMIN_KEY="$(entitybind login --scope admin --print-key --no-store)"
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Signing in with a different scope would replace the stored key and leave it
|
|
159
|
+
active, so `login` refuses that (`scope_change`) until you run
|
|
160
|
+
`entitybind logout --revoke`. Signing in again with the same scope replaces the
|
|
161
|
+
stored key and names the key it replaced, which stays active until it expires
|
|
162
|
+
or is revoked.
|
|
163
|
+
|
|
164
|
+
## Non-interactive use (CI)
|
|
165
|
+
|
|
166
|
+
Create a key once, keep it in your secret store, and pass it through the
|
|
167
|
+
environment. Nothing is stored on the runner.
|
|
168
|
+
|
|
169
|
+
```sh
|
|
170
|
+
entitybind login --scope resolve --print-key --no-store | your-secret-manager put entitybind
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
```yaml
|
|
174
|
+
- run: uvx entitybind@0.1.0 resolve --name "Acme Ltd" --country GB --json
|
|
175
|
+
env:
|
|
176
|
+
ENTITYBIND_API_KEY: ${{ secrets.ENTITYBIND_API_KEY }}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Pin the version in automation (`uvx entitybind@0.1.0`), so CI never runs a
|
|
180
|
+
release, or anything published under the name, that nobody reviewed.
|
|
181
|
+
`ENTITYBIND_API_KEY` and `ENTITYBIND_AML_KEY` override any stored credential.
|
|
182
|
+
`ENTITYBIND_BASE_URL` and `ENTITYBIND_AML_BASE_URL` (or `--base-url`) point the
|
|
183
|
+
client elsewhere; plain `http` is accepted only for `localhost`.
|
|
184
|
+
|
|
185
|
+
## Output and exit codes
|
|
186
|
+
|
|
187
|
+
Every command accepts `--json`. Successful API commands print the server's
|
|
188
|
+
JSON body; errors print `{"error": {...}, "status": ..., "exit_code": ...}` on
|
|
189
|
+
stdout, including any `remediation` the server returned. Progress goes to
|
|
190
|
+
stderr.
|
|
191
|
+
|
|
192
|
+
| Code | Meaning |
|
|
193
|
+
|---:|---|
|
|
194
|
+
| 0 | ok |
|
|
195
|
+
| 2 | usage error or invalid request |
|
|
196
|
+
| 3 | authentication or permission |
|
|
197
|
+
| 4 | payment or entitlement |
|
|
198
|
+
| 5 | not found |
|
|
199
|
+
| 6 | conflict |
|
|
200
|
+
| 7 | rate limited |
|
|
201
|
+
| 8 | server or network error |
|
|
202
|
+
| 9 | still pending or timed out |
|
|
203
|
+
|
|
204
|
+
`jobs wait` exits 0 for `succeeded`, 8 for `failed` or
|
|
205
|
+
`reconciliation_required`, 6 for `cancelled` and 5 for `erased`.
|
|
206
|
+
|
|
207
|
+
Requests carry `User-Agent: entitybind-cli/<version>` and
|
|
208
|
+
`X-EntityBind-Client: cli`. Mutating requests carry an `Idempotency-Key`
|
|
209
|
+
(pass `--idempotency-key` to choose it), and an error names the key it was
|
|
210
|
+
sent with; 429 and 503 responses are retried after the server's
|
|
211
|
+
`Retry-After`.
|
|
212
|
+
|
|
213
|
+
If `jobs submit` stops part-way (for example at the workspace's limit on
|
|
214
|
+
pending jobs), the error lists the jobs already accepted. Rerunning the same
|
|
215
|
+
command within 24 hours resumes the submission: it reuses the remembered
|
|
216
|
+
idempotency key, so the accepted jobs are recovered rather than queued again.
|
|
217
|
+
`--timeout` covers the whole `--wait`, and a passing 5xx or network failure
|
|
218
|
+
while waiting does not end it.
|
|
219
|
+
|
|
220
|
+
## Licence
|
|
221
|
+
|
|
222
|
+
MIT.
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "entitybind"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "EntityBind command-line client: log in, wire EntityBind into Claude Code, Codex, Gemini CLI, Cursor or VS Code, and call the Core API."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "EntityBind" }]
|
|
14
|
+
keywords = ["entitybind", "entity-resolution", "company-data", "mcp", "cli", "kyc"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 3 - Alpha",
|
|
17
|
+
"Environment :: Console",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"Operating System :: OS Independent",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
22
|
+
"Programming Language :: Python :: 3.10",
|
|
23
|
+
"Programming Language :: Python :: 3.11",
|
|
24
|
+
"Programming Language :: Python :: 3.12",
|
|
25
|
+
"Programming Language :: Python :: 3.13",
|
|
26
|
+
"Topic :: Utilities",
|
|
27
|
+
"Typing :: Typed",
|
|
28
|
+
]
|
|
29
|
+
dependencies = ["httpx>=0.27,<1"]
|
|
30
|
+
|
|
31
|
+
[project.optional-dependencies]
|
|
32
|
+
# Store credentials in the OS keyring (macOS Keychain, Secret Service, Windows
|
|
33
|
+
# Credential Locker) instead of the 0600 credentials file.
|
|
34
|
+
keyring = ["keyring>=24"]
|
|
35
|
+
|
|
36
|
+
[project.scripts]
|
|
37
|
+
entitybind = "entitybind.cli:main"
|
|
38
|
+
|
|
39
|
+
[project.urls]
|
|
40
|
+
Homepage = "https://app.entitybind.com"
|
|
41
|
+
Documentation = "https://app.entitybind.com/api/docs"
|
|
42
|
+
Source = "https://github.com/Tenhaw/entity-resolution/tree/main/clients/python"
|
|
43
|
+
|
|
44
|
+
[dependency-groups]
|
|
45
|
+
dev = [
|
|
46
|
+
"pytest>=8.2",
|
|
47
|
+
"pytest-cov>=5",
|
|
48
|
+
"ruff==0.16.8",
|
|
49
|
+
"mypy>=1.18,<2",
|
|
50
|
+
]
|
|
51
|
+
|
|
52
|
+
[tool.hatch.build.targets.wheel]
|
|
53
|
+
packages = ["src/entitybind"]
|
|
54
|
+
|
|
55
|
+
[tool.hatch.build.targets.sdist]
|
|
56
|
+
include = ["src/entitybind", "tests", "README.md", "LICENSE", "pyproject.toml"]
|
|
57
|
+
|
|
58
|
+
[tool.ruff]
|
|
59
|
+
line-length = 100
|
|
60
|
+
target-version = "py310"
|
|
61
|
+
src = ["src", "tests"]
|
|
62
|
+
|
|
63
|
+
[tool.ruff.lint]
|
|
64
|
+
select = ["E", "F", "W", "I", "N", "UP", "B", "S", "SIM", "RUF"]
|
|
65
|
+
|
|
66
|
+
[tool.ruff.lint.per-file-ignores]
|
|
67
|
+
"tests/*" = ["S", "SIM117"]
|
|
68
|
+
|
|
69
|
+
[tool.mypy]
|
|
70
|
+
python_version = "3.10"
|
|
71
|
+
files = ["src/entitybind"]
|
|
72
|
+
check_untyped_defs = true
|
|
73
|
+
disallow_untyped_defs = true
|
|
74
|
+
no_implicit_optional = true
|
|
75
|
+
warn_unused_ignores = true
|
|
76
|
+
warn_redundant_casts = true
|
|
77
|
+
strict_equality = true
|
|
78
|
+
|
|
79
|
+
[[tool.mypy.overrides]]
|
|
80
|
+
module = ["keyring", "keyring.*"]
|
|
81
|
+
ignore_missing_imports = true
|
|
82
|
+
|
|
83
|
+
[tool.pytest.ini_options]
|
|
84
|
+
testpaths = ["tests"]
|
|
85
|
+
addopts = "-p no:cacheprovider"
|
|
86
|
+
filterwarnings = ["error"]
|
|
87
|
+
|
|
88
|
+
[tool.coverage.run]
|
|
89
|
+
source = ["entitybind"]
|
|
90
|
+
branch = false
|
|
91
|
+
|
|
92
|
+
[tool.coverage.report]
|
|
93
|
+
fail_under = 90.0
|
|
94
|
+
precision = 2
|
|
95
|
+
show_missing = true
|
|
96
|
+
skip_covered = true
|
|
@@ -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"
|