entitybind
The command-line client for EntityBind. 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.
Version 0.1.2: PyPI and npm. Start with the Core API documentation or the separate AML API guide.
Set up from one coding-agent prompt
Give your coding agent this prompt, replacing codex with claude-code,
gemini, cursor or vscode for your client:
Set up EntityBind Core for this coding agent. Run
npx --yes entitybind@0.1.2 setup codex --json --no-browser(oruvx entitybind@0.1.2 setup codex --json --no-browserif Python/uv is available). Relay the device approval URL and code to me if requested; never ask me to paste an API key into chat. Wait for my approval, then repeat the command to resume. Report the credential and MCP verification results and whether I need to restart this client. Do not resolve companies or run paid work during setup.
For AML Onboard, change the product name and add --product aml. New Core users
create a workspace at https://app.entitybind.com/app; new AML users create a
synthetic-only sandbox at https://onboard.entitybind.com/signup and complete
email confirmation and MFA. AML production case admission remains closed.
setup combines credential acquisition, verification and client configuration.
It reuses an existing credential or resumes pending device approval, defaults
to a 50-second wait, and exits 9 while approval is pending. Repeat the same
command to continue; no additional device request is created while one is pending.
A person approves the connection in their browser. No key needs to pass through
chat or a manually exported environment variable.
Setup writes the credential into the client's private user configuration;
on POSIX systems the file is restricted to its owner. It never writes a raw
key into a project configuration. Existing unrelated settings are preserved;
a conflicting entry requires --force. Claude Code must be installed for its
native user-configuration command. Treat user config files as secrets; revoke
the key if one is exposed. The CLI's logout --revoke cannot remove a separate
copy from a client configuration, but the revoked key stops working there too.
Successful JSON reports credential_verified and mcp_verified separately
from native_client_session_verified. The read-only MCP handshake checks
initialization and visible tools without resolving a company or consuming
credits. Restart or reload your coding client to pick up its configuration.
A configuration write and direct protocol check do not establish that the
running native-client session has reloaded it.
For Core URL-only OAuth instead, run
entitybind setup codex --auth oauth --json. It configures the URL without a
key, returns authorization_required, and leaves approval to the native
client. Use codex mcp login entitybind, or your client's MCP authentication
flow. Cursor's private-scheme callback remains unsupported; use key setup.
AML MCP requires an agent key; partner keys are refused before writing config.
The lower-level login and mcp add commands below remain available when you
want to manage keys and environment references yourself.
Install
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
Create a Core workspace at app.entitybind.com/app, or a synthetic AML sandbox at onboard.entitybind.com/signup, and confirm your email. Each product has its own credentials and API origin. AML production case admission remains closed.
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 or local-development http on a loopback host.
Signing in from a coding agent
An agent's tool call may time out before a person approves. Use a time limit and resume:
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
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 into the MCP configuration.
The agent does not read the CLI's stored credential. 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:
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. Cursor's private-scheme callback has not been accepted by Core;
use static-key setup for Cursor. AML MCP always requires an AML key even though
the CLI uses a device flow to obtain one.
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
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:
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.
entitybind login --scope resolve --print-key --no-store | your-secret-manager put entitybind
- run: uvx entitybind@0.1.2 resolve --name "Acme Ltd" --country GB --json
env:
ENTITYBIND_API_KEY: ${{ secrets.ENTITYBIND_API_KEY }}
Pin the version in automation (uvx entitybind@0.1.2), 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 loopback hosts
(localhost, 127.0.0.1 or ::1).
Package installs and configuration previews have been verified. Actual native-client app sessions and Windows remain unverified; previewing or writing an entry alone does not establish a working client connection.
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.
Metadata
Release files for entitybind 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| entitybind-0.1.2.tar.gz | 94.2 kB | Without provenance | Details for entitybind-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| entitybind-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for entitybind-0.1.2-py3-none-any.whl |
Total release size: 164.4 kB
Release files / entitybind-0.1.2.tar.gz
| Download URL | entitybind-0.1.2.tar.gz |
|---|---|
| Size | 94.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dccd4496f2aa6e3869ac92c9de6e91adaa189770504cc895fe01a1091d5d3b79
|
|
BLAKE2b-256 checksum How to use checksums |
2611d9f41173073bdfd68445ad5d2648d60112f78ddf91bfdf2ab5d003c2b54b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / entitybind-0.1.2-py3-none-any.whl
| Download URL | entitybind-0.1.2-py3-none-any.whl |
|---|---|
| Size | 70.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dbd9995b21c7012ee3ead0d476f217bddd84165de4dc0a13fcb81aa938ec5e1c
|
|
BLAKE2b-256 checksum How to use checksums |
e9d7b99687e59618451d485e8bfce3f69ab861403c3add7b046c838c14039151
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for entitybind 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.