e-Próspera 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.

Install

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

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.

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

Goal	CLI command	Credentials	Scope
Verify an RPN	eprospera --json entity verify <rpn>	ak-, sk-	agent:verify_rpn
Search legal entities	eprospera --json entity search "<query>"	ak-, sk-	agent:registry.search
Fetch one legal entity	eprospera --json entity get <id>	ak-, sk-	agent:entity.read
Fetch entity documents	eprospera --json entity documents <id>	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 <id>	ak-, sk-	agent:entity.application.read
Pay with coupon	eprospera --json --yes application pay <id> --coupon <code>	ak-, sk-	agent:entity.application.pay
Watch until terminal state	eprospera --json application watch <id> --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:

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

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.

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:

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