@ensurance/cli
v0.1.0
Published
Privy-backed terminal access to Ensurance's shared execution services
Readme
Ensurance CLI
Privy login once, then supported swaps, transactions, approved programs and agent stewardship from the terminal. This package is a client of the same Ensurance OAuth, MCP, Act and execution services used by the app. It contains no wallet signer, private key, app secret, independent trading engine or browser transaction page.
The CLI and its programs permission need the matching backend release. A built package or passing fixture suite is not proof that a funded production trade has completed. Release, migration and live acceptance evidence belong to the pull request and the owning MCP feature plan.
Install and connect
Requires Node.js 20.11.1 or newer. From this repository, run directly:
node packages/cli/bin/ensurance.mjs help
node packages/cli/bin/ensurance.mjs loginOr install this local package:
npm install --global ./packages/cli
ensurance login
ensurance whoami
ensurance accounts --jsonThese local installation instructions do not imply an npm registry release. Publishing is a separate release action.
login displays a Privy authorization link. Open it once, sign in, review the named connection, enable wallet signing where needed, and choose limits. The default connection requests read act approve programs: account/status access, bounded manual actions, client-collected exact confirmation, and the app's program/autonomous controls. Use login --read-only for a connection that cannot spend or manage automation. An existing older connection needs fresh explicit consent; refreshing it cannot add permissions.
OAuth tokens live in the OS credential manager: macOS Keychain, Linux libsecret (secret-tool), or Windows PowerShell SecretManagement. Install and unlock the platform's credential manager before login. The CLI fails closed if it is unavailable; it never writes OAuth tokens to a local file. Sessions expire and can be revoked; “once” means the saved session refreshes between commands, not a permanent grant.
accounts reads the connected user's verified operator and controlled agent accounts for automation. Use those returned addresses in program and autonomous commands; do not infer ownership from a typed address or copy an account from an unrelated session. Discovery does not grant custody, delegation, funding or autonomous eligibility.
Use --profile NAME to keep separate connections, and --issuer https://your-service.example only for a trusted matching Ensurance deployment. Credentials cannot be redirected to a different origin. No command accepts a wallet private key or Ensurance server secret.
Natural language or commands
Use direct commands for scripts, or ask in ordinary language:
ensurance ask "swap 1 USDC for ENSURE"
ensurance ask "show my approved programs for 0x1111111111111111111111111111111111111111"
ensurance chatask sends one request through the existing Act planning/model layer. chat keeps a bounded conversation in the terminal; type exit or quit to leave. The planner may answer, request clarification or select one validated supported tool. It cannot call a signer, choose an execution idempotency key or turn model prose into spend authority. A proposed financial action follows the same server proposal, exact terminal confirmation and durable execution path as its direct command. Ambiguous accounts, amounts or actions must be clarified.
Read/planning requests work headlessly with ask --json; a new financial approval still requires a TTY. Chat requires a TTY. --json chat output is one JSON line per returned turn, followed by its closing result. No local model API key is needed: model admission and billing use the app's existing Act rules.
Swaps and transactions
ensurance swap 1 USDC ENSURE
ensurance send 0.0001 ETH --to 0x2222222222222222222222222222222222222222
ensurance transaction --file transaction.jsonThose addresses and amounts are examples, not instructions to send funds. Replace the recipient and review the actual server terms. Manual execution displays the immutable source, chain, amount, minimum output or recipient, calldata, costs, current limits and expiry. Type the full word yes to approve; blank, y, or any other response declines. Confirmation happens in the terminal, not a separate browser transaction visit. Piped/headless commands cannot approve a fresh action. There is no --yes bypass.
transaction.json contains exactly:
{
"chainId": 8453,
"to": "0x2222222222222222222222222222222222222222",
"value": "100000000000000",
"data": "0x",
"description": "Send 0.0001 ETH to my reviewed recipient"
}Values are integer wei, never floating point. The backend accepts only the supported native transfer, decoded catalog ERC-20 transfer, or finite catalog-token approval. A transaction file does not enable arbitrary calldata, unlimited approvals, NFTs or protocol wallets. Manual swaps use the connected person's own Privy embedded EOA on Base and require a catalog instrument on at least one side; catalog, fee and economics rules remain enforced by shared core. Manual TBA swaps are not added by this CLI.
Prepare without signing, or obtain an unsigned quote for your own external wallet:
ensurance swap 1 USDC ENSURE --prepare --json
ensurance execute PROPOSAL_ID
ensurance quote 1 USDC ENSURE --wallet 0x1111111111111111111111111111111111111111 --jsonQuote output is unsigned: the caller's separate wallet signs and submits it. The CLI does not import or use an external wallet key.
Receipts, retries and interrupted commands
ensurance status --operation OPERATION_ID --json
ensurance status --proposal PROPOSAL_ID --json
ensurance tx status OPERATION_ID
ensurance resume SAVED_OPERATION_IDEach write saves its exact arguments and stable idempotency key before submission. A private local journal also keeps the bound confirmation continuation so an interrupted command can resume the same operation. It is isolated by issuer, profile, account and OAuth client; files are mode 0600, and OAuth tokens are never included. Sealed continuation state is never printed. Do not share the journal: it contains private account/action metadata.
An interrupted response does not mean a transaction failed. Inspect status and resume the saved operation printed by the error. Do not create a replacement trade while submission is uncertain. Reusing an operation ID with changed arguments is refused. A pending/unknown result remains pending/unknown; a hash alone is not confirmed success. The server's durable operation service owns signing, caps, uncertain broadcast handling and chain receipts.
For repeatable scripts, supply --idempotency-key YOUR_STABLE_KEY (16–128 letters, numbers, hyphens or underscores). Repeating the same manual command with that key resumes its original proposal; a changed action under that key is refused. For scheduled app runs, reuse the same key only when recovering the same run; choose a new key for an intentionally new run.
A hard-killed process can leave a profile or operation lock. The CLI refuses to steal a live lock. Inspect its recorded PID (owner.json in a profile lock, or the action lock file itself), confirm that process is dead and no other Ensurance CLI command is running, and inspect server status/history before deleting a lock. Never infer a dead process from the lock's age alone. If a stale profile lock prevents the CLI read, inspect the existing app history first.
Profile locks are <profile-hash>.lock/ directories under ~/Library/Application Support/ensurance/cli on macOS, ${XDG_STATE_HOME:-~/.local/state}/ensurance-cli on Linux, or %LOCALAPPDATA%/ensurance/cli on Windows. Action locks are <saved-operation-id>.json.lock files below the connection hash in ~/.local/state/ensurance/operations (Windows: %LOCALAPPDATA%/ensurance/operations). Remove only the confirmed stale lock file/directory, then resume the original saved operation. Keep the journal JSON, Keychain/libsecret/SecretManagement entries, and any other credential files. Deleting a lock or journal is not transaction cancellation; do not resolve uncertainty by submitting a new-key trade.
Automated programs
Automated mode runs an explicitly approved configured routine using the app's program registry, schedule, allowance and signer checks. It does not repeatedly auto-answer manual swap confirmations. Discover the actual kinds and configuration variables first:
ensurance programs kinds --json
ensurance accounts --json
ensurance programs list ACCOUNT_ADDRESS --json
ensurance programs create --file program.json
ensurance programs run ACCOUNT_ADDRESS PROGRAM_ID --json
ensurance programs history ACCOUNT_ADDRESS PROGRAM_ID --limit 20 --json
ensurance programs pause ACCOUNT_ADDRESS PROGRAM_ID
ensurance programs archive ACCOUNT_ADDRESS PROGRAM_IDFor example, this creates an on-demand app diversifier with one allowed run:
{
"accountAddress": "0x1111111111111111111111111111111111111111",
"type": "diversifier",
"config": { "diversificationPercent": 0.2, "targetTokenCount": 1 },
"caps": { "maxExecutions": 1 },
"schedule": null
}The account must actually be controlled by the connected user and be eligible for the existing app runner. The exact configuration, source, allowance and cadence are displayed for terminal confirmation. maxExecutions limits runs, not dollars. Program sizing comes from the selected kind's validated configuration; this CLI does not invent a new USD cap for that legacy runner. A non-null schedule uses the app scheduler after approval, so the terminal can close. Existing run allowances, custody, delegation, activation, fees and other app checks still apply.
Autonomous accounts
Autonomous mode runs the existing agent steward from its identity and mandate. It does not give a local LLM unrestricted access to an embedded wallet:
ensurance autonomous show AGENT_TBA_ADDRESS --json
ensurance autonomous enable --file autonomous.json
ensurance autonomous run AGENT_TBA_ADDRESS --json
ensurance autonomous pause AGENT_TBA_ADDRESSAn example activation file:
{
"accountAddress": "0x1111111111111111111111111111111111111111",
"perActionCap": 1,
"perWindowCap": 5,
"windowDuration": "24h",
"wakeIntervalMinutes": 30
}Caps are positive USD amounts; the window cap must cover the per-action cap. Optional token, recipient and protocol allowlists are validated by the app. Enabling or changing authority requires exact terminal confirmation. The existing app controls which owned agent TBAs can run: current operator custody, wallet delegation, autonomous settings, mandate/identity, funding and economic activation. An operator EOA is not silently promoted to an autonomous agent. This CLI does not change the app permission matrix.
Already approved program runs and enabled steward wakes can be invoked headlessly, with an optional caller-chosen stable --idempotency-key. Their results can be inspected with automation status IDEMPOTENCY_KEY, and an interrupted control request can be resumed using its saved ID. A running/unknown control request is not executed again merely because its response was lost.
Stop automation and disconnect
Pause/archive programs and disable the steward to stop future runs. Closing the terminal, logging out, or revoking the CLI connection does not cancel app-approved standing programs or steward mandates. They are the same app automation, not jobs owned by this local process. The exact activation confirmation states this distinction. Already submitted chain transactions cannot be cancelled by any disconnect.
ensurance programs pause ACCOUNT_ADDRESS PROGRAM_ID
ensurance autonomous pause AGENT_TBA_ADDRESS
ensurance logoutLogout revokes the OAuth family and removes the local credential. Ensurance Settings also provides connection revocation. If network revocation fails, logout removes the local credential and reports that server revocation still needs attention.
Structured output and tests
--json writes one result object to stdout. Prompts, login links and errors go to stderr; confirmation still requires a TTY. Terminal control characters in service text are escaped. Exit 0 means the command returned a valid accepted/pending/confirmed result, not necessarily a settled transaction. Rejection, failure, uncertainty or invalid usage is reported separately; check the state and receipts.
node --test packages/cli/test/*.mjsThe package uses Node built-ins and has no external runtime dependencies. A hosted assistant invoking it still has its own tool permissions and platform policies; CLI packaging does not establish universal hosted-chat trading support.
