# 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 ``` To update an existing installation and confirm the installed version: ```bash npm install -g @prospera/eprospera-cli@latest eprospera --version ``` The CLI requires a modern Node.js runtime. See the [`@prospera/eprospera-cli` npm package](https://www.npmjs.com/package/@prospera/eprospera-cli) for the published version and [GitHub Releases](https://github.com/Honduras-Prospera-inc/eprospera-cli/releases) for release notes and standalone bundles. ## 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. For user, consented-entity, and tax reads, authorize the official CLI with your e-Próspera account: ```bash eprospera auth login --oauth ``` The CLI uses device authorization, opens the consent page in a browser, and stores access and refresh tokens in the OS keychain when available. Access tokens refresh automatically. `eprospera --yes auth logout` attempts to revoke the remote tokens before deleting the local credential. ## 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 owned 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` | | Create hosted checkout | `eprospera --json --yes application checkout --redirect-url --provider ` | `sk-` | — | | 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` or `eprospera:person.details.read` | | Read owner residency | `eprospera --json me residency` | `ak-`, OAuth | `agent:person.residency.read` or `eprospera:person.residency.read` | | Read ID verification | `eprospera --json me id-verification` | `ak-`, OAuth | `agent:person.id_verification.read` or `eprospera:person.id_verification.read` | | List consented entities | `eprospera --json me legal-entities list` | OAuth | `eprospera:entity.read` | | Read a consented entity | `eprospera --json me legal-entities get ` | OAuth | `eprospera:entity.read` | | Read consented documents | `eprospera --json me legal-entities documents ` | OAuth | `eprospera:entity.documents.read` | | Show tax obligations | `eprospera --json tax status --subject ` | OAuth | `eprospera:person.tax.read` or `eprospera:entity.tax.read` | | List tax filings | `eprospera --json tax list --subject --year 2025` | OAuth | `eprospera:person.tax.read` or `eprospera:entity.tax.read` | | Read a tax filing | `eprospera --json tax get ` | OAuth | `eprospera:person.tax.read` or `eprospera:entity.tax.read` | | Download a tax document | `eprospera tax download --document assessment` | OAuth | `eprospera:person.tax.read` or `eprospera:entity.tax.read` | | List referral attribution | `eprospera --json referral list ` | `sk-` | — | | Submit a visitor pass | `eprospera --json --yes visitor-pass create ` | None | — | 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. In staging, voucher `API1234` covers every product; Stripe checkout uses test card `ACCT-000015` — [Testing in staging](/testing-in-staging). ### Create a hosted checkout with a standard key [#create-a-hosted-checkout-with-a-standard-key] ```bash eprospera --json --yes application checkout \ --redirect-url https://example.com/return \ --provider stripe ``` Hosted checkout requires a standard `sk-...` key and an API-created Draft application. Agent Keys cannot create checkout sessions; use a fully covering voucher or let the resident complete payment in the portal instead. Standard keys can list portal-created applications, but voucher payment and checkout still require `createdViaAPI`. ### 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. ### Read taxes and download filed documents [#read-taxes-and-download-filed-documents] Tax responses and PDFs contain confidential financial information. The CLI can only read the signed-in user's records or a legal entity selected during consent; it cannot read other users' data or an entity that was not selected. See [Tax and legal-entity data](/tax-and-entity-data) for the complete access model and handling guidance. ```bash eprospera auth login --oauth eprospera --json tax status --subject personal eprospera --json tax list --subject personal --type income --year 2025 eprospera --json tax get eprospera --json tax download --document assessment ``` Use a consented legal-entity UUID as `--subject` for entity taxes. Downloads refuse to overwrite an existing file unless you pass `--yes`. ### Inspect referrals or submit a visitor pass [#inspect-referrals-or-submit-a-visitor-pass] Referral attribution requires a standard key. Visitor-pass submission is a public workflow and does not require a credential: ```bash eprospera --json referral list EXAMPLE_CODE eprospera --json --yes visitor-pass create \ --first-name Ada \ --last-name Lovelace \ --date-of-birth 1990-01-01 \ --email ada@example.test \ --signature "Ada Lovelace" \ --consent-to-background-check \ --referral-source "Prospera website" ``` ## 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 | Reauthorize or request 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 to implement your own OAuth flow or client. * 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), [Standard API Keys](/standard-keys), [Agent Keys](/agent-keys), and the endpoint reference pages.