e-Próspera CLI

Source repository: Honduras-Prospera-inc/eprospera-cli.

Install

npm install -g @prospera/eprospera-cli
eprospera --help

To update an existing installation and confirm the installed version:

npm install -g @prospera/eprospera-cli@latest
eprospera --version

The CLI requires a modern Node.js runtime. See the @prospera/eprospera-cli npm package for the published version and GitHub Releases for release notes and standalone bundles.

Authenticate

The CLI resolves credentials in this order:

1. --api-key <value>
2. EPROSPERA_API_KEY
3. Credentials saved by eprospera auth login

For one-off automation, pass the key explicitly or through the environment:

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:

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:

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

For automation, prefer this shape:

eprospera --json --yes <group> <command>

• --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=<url> overrides the API base URL for trusted endpoints.

Parse stdout as data. Treat stderr as diagnostics.

Command Matrix

The CLI also includes auth, config, completion, and schema commands:

eprospera --json auth whoami
eprospera --json config list
eprospera completion zsh
eprospera schema

Common Workflows

Verify and fetch an entity

eprospera --json entity verify 80000000000012
eprospera --json entity search 80000000000012
eprospera --json entity get <id>

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

eprospera --json --dry-run application create --file application.json
eprospera --json --yes application create --file application.json
eprospera --json --yes application pay <application-id> --voucher FOUNDER100
eprospera --json application watch <application-id> --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 for a complete request file and failure handling.

Create a hosted checkout with a standard key

eprospera --json --yes application checkout <application-id> \
  --redirect-url https://example.com/return \
  --provider stripe

Hosted checkout requires a standard sk-... key and an API-created application. Agent Keys cannot create checkout sessions; use a fully covering voucher or let the resident complete payment in the portal instead.

Read the key owner

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

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 for the complete access model and handling guidance.

eprospera auth login --oauth
eprospera --json tax status --subject personal
eprospera --json tax list --subject personal --type income --year 2025
eprospera --json tax get <filing-id>
eprospera --json tax download <filing-id> --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

Referral attribution requires a standard key. Visitor-pass submission is a public workflow and does not require a credential:

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

Machine-mode errors use this shape:

{
  "error": {
    "code": "INVALID_USAGE",
    "message": "Human-readable failure.",
    "details": {}
  }
}

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, Agent Keys, and the endpoint reference pages.