Skip to main content

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.

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

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:

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 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:

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

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.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.

Metadata

Release files for entitybind 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for entitybind 0.1.1
File Size Uploaded Provenance Actions
entitybind-0.1.1.tar.gz 83.9 kB Without provenance Details for entitybind-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for entitybind 0.1.1
File Interpreter ABI Platform Actions
entitybind-0.1.1-py3-none-any.whl Python 3 none any Details for entitybind-0.1.1-py3-none-any.whl

Total release size: 146.2 kB

Release files / entitybind-0.1.1.tar.gz

Download URL entitybind-0.1.1.tar.gz
Size 83.9 kB
Tags Source
SHA-256 checksum
How to use checksums
3f4c1206ce71b8360d2c800bd08b18bddf2cb556e29e712725e6149f2da4f33a
BLAKE2b-256 checksum
How to use checksums
b6269d64e8da7df5eaee5b44f12cb4102b8146d844e17c0d5f3de7631287706a
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.1-py3-none-any.whl

Download URL entitybind-0.1.1-py3-none-any.whl
Size 62.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
75acd4c6142631ad9b1c8fbf2fed229d972617a621cdac8da5cb17fefe1978b0
BLAKE2b-256 checksum
How to use checksums
bf7e408299eb9846a13594e8fc87450cf2a9bdd59ed26cdaee7e083b6e930ed4
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.1

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page