# e-Próspera CLI (/cli) The official CLI wraps the public API in commands that are easier for humans, scripts, CI jobs, and AI agents to call safely. Use it when your runtime can execute shell commands. Use direct HTTP only when you are building your own client, need an endpoint the CLI does not cover, or cannot install Node tooling. Source repository: [Honduras-Prospera-inc/eprospera-cli](https://github.com/Honduras-Prospera-inc/eprospera-cli). ## Install [#install] ```bash npm install -g @prospera/eprospera-cli eprospera --help ``` The CLI requires a modern Node.js runtime. See the GitHub repository for the current supported Node versions and release notes. ## Authenticate [#authenticate] The CLI resolves credentials in this order: 1. `--api-key ` 2. `EPROSPERA_API_KEY` 3. Credentials saved by `eprospera auth login` For one-off automation, pass the key explicitly or through the environment: ```bash export EPROSPERA_API_KEY="ak-..." eprospera --json entity verify 80000000000012 ``` To store an Agent Key for later commands, cache the scopes you granted in the portal: ```bash eprospera --api-key "$EPROSPERA_API_KEY" auth login \ --agent-key \ --scopes agent:verify_rpn,agent:registry.search,agent:entity.read ``` Use `--standard-key` instead of `--agent-key` for a standard `sk-...` key. Agent Keys remain scope-checked by the API; cached scopes are a local preflight and do not grant permissions by themselves. ## Agent Mode [#agent-mode] For automation, prefer this shape: ```bash eprospera --json --yes ``` * `--json` prints machine-readable JSON and suppresses spinners and color. * `--raw` prints compact single-line JSON when token efficiency matters. * `--fields id,statusId,name` trims read output to selected top-level fields. * `--yes` skips confirmation prompts for write commands. * `--dry-run` validates locally and prints the request that would be sent. * `EPROSPERA_ENV=staging` points the CLI at staging. * `EPROSPERA_BASE_URL=` overrides the API base URL for trusted endpoints. Parse stdout as data. Treat stderr as diagnostics. ## Command Matrix [#command-matrix] | Goal | CLI command | Credentials | Scope | | ----------------------------- | ------------------------------------------------------------------- | ------------ | ----------------------------------- | | Verify an RPN | `eprospera --json entity verify ` | `ak-`, `sk-` | `agent:verify_rpn` | | Search legal entities | `eprospera --json entity search ""` | `ak-`, `sk-` | `agent:registry.search` | | Fetch one legal entity | `eprospera --json entity get ` | `ak-`, `sk-` | `agent:entity.read` | | Fetch entity documents | `eprospera --json entity documents ` | `ak-`, `sk-` | `agent:entity.documents.read` | | List API-created applications | `eprospera --json application list` | `ak-`, `sk-` | `agent:entity.application.read` | | Create an application | `eprospera --json --yes application create --file application.json` | `ak-`, `sk-` | `agent:entity.application.create` | | Fetch one application | `eprospera --json application get ` | `ak-`, `sk-` | `agent:entity.application.read` | | Pay with voucher | `eprospera --json --yes application pay --voucher ` | `ak-`, `sk-` | `agent:entity.application.pay` | | Watch until terminal state | `eprospera --json application watch --timeout 30m` | `ak-`, `sk-` | `agent:entity.application.read` | | Read owner profile | `eprospera --json me profile` | `ak-`, OAuth | `agent:person.details.read` | | Read owner residency | `eprospera --json me residency` | `ak-`, OAuth | `agent:person.residency.read` | | Read ID verification | `eprospera --json me id-verification` | `ak-`, OAuth | `agent:person.id_verification.read` | The CLI also includes `auth`, `config`, `completion`, and `schema` commands: ```bash eprospera --json auth whoami eprospera --json config list eprospera completion zsh eprospera schema ``` ## Common Workflows [#common-workflows] ### Verify and fetch an entity [#verify-and-fetch-an-entity] ```bash eprospera --json entity verify 80000000000012 eprospera --json entity search 80000000000012 eprospera --json entity get ``` `entity verify` confirms whether the RPN is known and active. It does not return the legal-entity UUID, so use `entity search` before `entity get`. ### Create, pay, and watch an LLC application [#create-pay-and-watch-an-llc-application] ```bash eprospera --json --dry-run application create --file application.json eprospera --json --yes application create --file application.json eprospera --json --yes application pay --voucher FOUNDER100 eprospera --json application watch --timeout 30m ``` Write-capable Agent Keys require an active Manifestation of Will. Fully headless incorporation also requires the owner to pre-accept the Agreement of Coexistence for the target residency type. See [Agent recipes](/agent-recipes) for a complete request file and failure handling. ### Read the key owner [#read-the-key-owner] ```bash eprospera --json --fields id,fullName,email me profile eprospera --json me residency eprospera --json me id-verification ``` These commands accept Agent Keys or OAuth credentials. Standard `sk-...` keys are not valid for `me` commands. ## Exit Codes [#exit-codes] | Code | Meaning | Agent behavior | | ---- | ------------------------------------ | ------------------------------------------------- | | `0` | Success | Continue. | | `1` | Unexpected failure | Surface the error and stop. | | `2` | Invalid usage | Fix command syntax or inspect `eprospera schema`. | | `3` | Authentication failure | Ask for a credential or run `auth login`. | | `4` | Authorization failure | Ask for a key with the missing scope. | | `5` | Resource not found | Stop retrying the same lookup. | | `6` | Conflict | Ask for different input or state. | | `7` | Rate limit | Respect `Retry-After` and retry later. | | `8` | Validation error | Fix local input using `error.details`. | | `9` | Timeout | Surface the last polling state. | | `10` | Terminal application/payment failure | Stop and ask for new input. | Machine-mode errors use this shape: ```json { "error": { "code": "INVALID_USAGE", "message": "Human-readable failure.", "details": {} } } ``` ## When to Use Direct HTTP [#when-to-use-direct-http] Use the REST reference pages and `curl` examples when: * You are building an SDK, service integration, or browser/backend client. * You need OAuth authorization-code flows. * You need an endpoint the CLI does not cover. * You want exact wire-level request and response shapes. For direct HTTP rules, see [Conventions](/conventions), [Agent Keys](/agent-keys), and the endpoint reference pages.