Metadata-Version: 2.5
Name: entitybind
Version: 0.1.1
Summary: EntityBind command-line client: log in, wire EntityBind into Claude Code, Codex, Gemini CLI, Cursor or VS Code, and call the Core API.
Project-URL: Homepage, https://app.entitybind.com
Project-URL: Documentation, https://app.entitybind.com/api/docs
Project-URL: Source, https://github.com/Tenhaw/entity-resolution/tree/main/clients/python
Author: EntityBind
License-Expression: MIT
License-File: LICENSE
Keywords: cli,company-data,entity-resolution,entitybind,kyc,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: keyring
Requires-Dist: keyring>=24; extra == 'keyring'
Description-Content-Type: text/markdown

# entitybind

The command-line client for [EntityBind](https://app.entitybind.com). It signs
a person or a coding agent in, wires EntityBind's MCP servers into Claude Code,
Codex, Gemini CLI, Cursor or VS Code, and calls the Entity Bind - Core API:
resolve, quote, registry discovery, batch jobs, usage, billing, keys and
decision receipts.

It has one runtime dependency (`httpx`), needs Python 3.10 or later, and talks
only to the EntityBind origins you point it at.

## Install

```sh
uvx entitybind --help                    # run without installing
pipx install entitybind                  # or install it as a tool
pipx install 'entitybind[keyring]'       # store credentials in the OS keyring
```

The npm package of the same name provides `login`, `logout`, `whoami` and
`mcp add` for machines without Python: `npx entitybind login`.

## Sign in

```sh
entitybind login                         # Entity Bind - Core
entitybind login --product aml           # AML Onboard
```

`login` uses the OAuth device flow (RFC 8628). It prints a link and a short
code, opens your browser, and waits while you approve the request as the
workspace owner. The resulting key is stored:

- in the OS keyring, when `entitybind[keyring]` is installed and a keyring
  backend works; otherwise
- in `$XDG_CONFIG_HOME/entitybind/credentials.json` (default `~/.config`),
  mode 0600 in a 0700 directory.

Credentials are kept per product and base URL. `entitybind whoami` shows which
credential is in use; `entitybind logout` removes it. `--revoke` revokes the
key on the server first and removes the local copy only once the server
confirms the key no longer works; otherwise it exits non-zero
(`revocation_unconfirmed`), keeps the local copy and names the key id.

AML device login is for sandbox workspaces and needs an MFA administrator's
approval. In a self-serve workspace it reports `simulated_checks_only: true`
in JSON and explains that checks use synthetic providers only.

Useful options: `--scope` (Core: `read`, `resolve`, `review` or `admin`,
default `resolve`; AML: `agent`, the default, `partner`, or AML scope names),
`--name` (a suggested key label; current servers ignore it and the key is
named when it is approved), `--no-browser`, `--print-key` (print the key
once on stdout, for a secret manager), and `--no-store` (only with
`--print-key`, so the key is never discarded). The browser is opened only for
an `https` link.

### Signing in from a coding agent

An agent's tool call may time out before a person approves. Use a time limit
and resume:

```sh
entitybind login --no-browser --timeout 50 --json   # exits 9 while waiting
entitybind login --resume --timeout 50 --json       # repeat until it exits 0
```

With `--json`, the link and code are printed on stderr as a JSON event for the
agent to relay to the person; stdout carries one JSON result. A started sign-in
is saved (mode 0600) until it is approved, denied or expires.

## Wire EntityBind into your agent

```sh
entitybind mcp add claude-code            # print the entry for ./.mcp.json
entitybind mcp add claude-code --write    # merge it into ./.mcp.json
entitybind mcp add codex --write          # ~/.codex/config.toml
entitybind mcp add gemini --write         # ./.gemini/settings.json
entitybind mcp add cursor --write         # ./.cursor/mcp.json
entitybind mcp add vscode --write         # ./.vscode/mcp.json
entitybind mcp add claude-code --product aml --write
```

`--auth key` (the default) sends `Authorization: Bearer` with the key taken
from an environment variable, `ENTITYBIND_API_KEY` for Core or
`ENTITYBIND_AML_KEY` for AML, so no key is written to disk. A plain `login`
never prints the stored key, so get one for the agent with `--print-key`, and
set the variable for that agent's process or project only, not in your shell
profile:

```sh
export ENTITYBIND_API_KEY="$(entitybind login --print-key --no-store)"   # this shell only
claude
```

Headless agents such as `claude -p` load a repository's committed `.mcp.json`
without asking, so a hostile repository could name the same variable for its
own server and receive an exported key. `--inline-key` writes the raw key instead (with a
warning, mode 0600), and only into a user-scope file: it is refused for
project files such as `./.mcp.json`, which are usually committed, so add
`--scope user`.

`--auth oauth` (Core only) configures just the URL. The client registers
itself and the workspace owner approves the connection in the browser: run
`/mcp` in Claude Code, `codex mcp login entitybind`, or `/mcp auth entitybind`
in Gemini CLI.

Other options: `--scope project|user` (Codex defaults to `user`, the others to
`project`), `--dir`, `--server-name`, and `--force` to update the URL and
credential settings of an existing entry of the same name. Settings you added
to the entry yourself (timeouts, trust, tool filters, Codex approval modes)
are never a conflict and are kept, with or without `--force`. Merging keeps everything else in the file, writes
atomically, and refuses files it cannot rewrite safely (for example JSON with
comments) rather than reformatting them. Claude Code's user scope is written by
running `claude mcp add-json` for you.

Gemini CLI blanks environment variables whose names contain `KEY` when it
expands headers, so `mcp add gemini` also adds the variable to
`security.environmentVariableRedaction.allowed`.
With `--json`, the `configuration` field contains the complete JSON fragment,
including that allowlist, for an agent to apply.

## Use the Core API

```sh
entitybind resolve --name "Acme Ltd" --country GB --postcode "SW1A 1AA"
entitybind resolve --input record.json --async --wait --json
entitybind quote --csv suppliers.csv --map name="Company Name" --default-country GB
entitybind discover --name "Acme" --country GB
entitybind jobs submit --csv suppliers.csv --map name="Company Name" \
    --key-column "Supplier ID" --default-country GB --wait
entitybind jobs list
entitybind jobs results job_... --format csv --output results.csv
entitybind usage --since 2026-11-01
entitybind billing status
entitybind billing checkout --plan starter     # prints a link for a person to pay
entitybind keys create --name ci --scope resolve --expires-in 30d   # admin key
entitybind decisions get dec_...
```

`jobs submit` maps CSV columns the same way as the repository's
`resolvd import-csv`: `--map field=Column` (repeatable, comma-separable), and
columns already named after a field map automatically. Rows without a name or
country are refused unless you pass `--skip-invalid` (in `quote --csv` too, so
a quote never silently covers fewer rows than the file). Large files are split
into jobs of `--chunk-size` records (default 500, Core's default batch limit;
`GET /v1/reference/limits` reports a deployment's `max_batch_size`). A
workspace may have only a limited number of jobs pending at once (ten by
default), so very large files may need `--wait` between runs.

`keys` commands need an admin-scoped key. Core scopes do not overlap, so keep
your everyday key stored and pass an admin key through the environment for key
management:

```sh
export ENTITYBIND_ADMIN_KEY="$(entitybind login --scope admin --print-key --no-store)"
```

Signing in with a different scope would replace the stored key and leave it
active, so `login` refuses that (`scope_change`) until you run
`entitybind logout --revoke`. Signing in again with the same scope replaces the
stored key and names the key it replaced, which stays active until it expires
or is revoked.

## Non-interactive use (CI)

Create a key once, keep it in your secret store, and pass it through the
environment. Nothing is stored on the runner.

```sh
entitybind login --scope resolve --print-key --no-store | your-secret-manager put entitybind
```

```yaml
- run: uvx entitybind@0.1.1 resolve --name "Acme Ltd" --country GB --json
  env:
    ENTITYBIND_API_KEY: ${{ secrets.ENTITYBIND_API_KEY }}
```

Pin the version in automation (`uvx entitybind@0.1.1`), so CI never runs a
release, or anything published under the name, that nobody reviewed.
`ENTITYBIND_API_KEY` and `ENTITYBIND_AML_KEY` override any stored credential.
`ENTITYBIND_BASE_URL` and `ENTITYBIND_AML_BASE_URL` (or `--base-url`) point the
client elsewhere; plain `http` is accepted only for `localhost`.

## Output and exit codes

Every command accepts `--json`. Successful API commands print the server's
JSON body; errors print `{"error": {...}, "status": ..., "exit_code": ...}` on
stdout, including any `remediation` the server returned. Progress goes to
stderr.

| Code | Meaning |
|---:|---|
| 0 | ok |
| 2 | usage error or invalid request |
| 3 | authentication or permission |
| 4 | payment or entitlement |
| 5 | not found |
| 6 | conflict |
| 7 | rate limited |
| 8 | server or network error |
| 9 | still pending or timed out |

`jobs wait` exits 0 for `succeeded`, 8 for `failed` or
`reconciliation_required`, 6 for `cancelled` and 5 for `erased`.

Requests carry `User-Agent: entitybind-cli/<version>` and
`X-EntityBind-Client: cli`. Mutating requests carry an `Idempotency-Key`
(pass `--idempotency-key` to choose it), and an error names the key it was
sent with; 429 and 503 responses are retried after the server's
`Retry-After`.

If `jobs submit` stops part-way (for example at the workspace's limit on
pending jobs), the error lists the jobs already accepted. Rerunning the same
command within 24 hours resumes the submission: it reuses the remembered
idempotency key, so the accepted jobs are recovered rather than queued again.
`--timeout` covers the whole `--wait`, and a passing 5xx or network failure
while waiting does not end it.

## Licence

MIT.
