openany-cli-dev 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/README.md +19 -19
  2. package/package.json +1 -1
  3. package/skills/openany/SKILL.md +17 -336
  4. package/skills/openany/calls.md +116 -0
  5. package/skills/openany/setup.md +235 -0
  6. package/skills/openany/topups.md +70 -0
  7. package/skills/openany-provider/SKILL.md +6 -2
  8. package/skills/openany-provider/SKILL.zh-CN.md +6 -2
  9. package/skills/openany-provider/references/apis.md +5 -5
  10. package/skills/openany-provider/references/apis.zh-CN.md +4 -4
  11. package/skills/openany-provider/references/application.md +1 -1
  12. package/skills/openany-provider/references/application.zh-CN.md +1 -1
  13. package/skills/openany-provider/references/connections.md +8 -8
  14. package/skills/openany-provider/references/connections.zh-CN.md +7 -7
  15. package/skills/openany-provider/references/imports.md +3 -3
  16. package/skills/openany-provider/references/imports.zh-CN.md +3 -3
  17. package/skills/openany-provider/references/models.md +8 -8
  18. package/skills/openany-provider/references/models.zh-CN.md +5 -5
  19. package/skills/openany-provider/references/publishing.md +3 -3
  20. package/skills/openany-provider/references/publishing.zh-CN.md +4 -4
  21. package/skills/openany-provider/references/reviews.md +2 -2
  22. package/skills/openany-provider/templates/bindings.json +1 -1
  23. package/skills/openany-provider/templates/models-v2.json +12 -12
  24. package/skills/openany-provider/templates/models.json +2 -2
  25. package/skills/openany-provider/templates/provider-agent-api-template.json +12 -12
  26. package/skills/openany-provider/templates/seller-agent-api-import-template.json +16 -16
  27. package/src/cli.js +12 -4
  28. package/src/provider-connections.js +2 -2
  29. package/src/provider-imports.js +5 -4
  30. package/src/provider-model-import-v2.js +10 -1
  31. package/src/provider.js +5 -3
  32. package/src/seller-fields.js +57 -0
package/README.md CHANGED
@@ -4,7 +4,7 @@ OpenAny CLI is a standalone Node.js CLI that provides access to OpenAny models,
4
4
 
5
5
  The backend and signing origin are fixed at `https://dev.openany.si`. Model calls use the `https://api-dev.openany.si` gateway and take their paths and query parameters from the public catalog's `curlExample`.
6
6
 
7
- The skill is available in [Chinese](skills/openany/SKILL.zh-CN.md) and [English](skills/openany/SKILL.md). Both files ship with the npm package.
7
+ The skill is available in [Chinese](skills/openany/SKILL.zh-CN.md) and [English](skills/openany/SKILL.md). Both entries and the English task guides ship with the npm package.
8
8
 
9
9
  ## Installation
10
10
 
@@ -16,7 +16,7 @@ openany-dev --version
16
16
  openany-dev --help
17
17
  ```
18
18
 
19
- The npm package is `openany-cli-dev`, and the command is `openany-dev`. The package includes `skills/openany/SKILL.md`. Run `npm root -g` to locate the global installation directory, then install `openany-cli-dev/skills/openany` from that directory into your agent's skill directory. Update the skill whenever you update the CLI.
19
+ The npm package is `openany-cli-dev`, and the command is `openany-dev`. The package includes the entry and task guides in `skills/openany`. Run `npm root -g` to locate the global installation directory, then install `openany-cli-dev/skills/openany` from that directory into your agent's skill directory. Update the skill whenever you update the CLI.
20
20
 
21
21
  To develop from source or build a local installation package, run:
22
22
 
@@ -147,7 +147,7 @@ See the [skill documentation](skills/openany/SKILL.md) for detailed instructions
147
147
  `openany-dev setup` offers three setup options in an interactive terminal. You can also select one directly with a flag:
148
148
 
149
149
  - `--api_key api_key` prompts for a key label, the API key using masked input, and whether to activate it. Updating a key with the same label replaces its value.
150
- - `--wallet_connect wallet` prompts for the wallet private key using masked input, derives the address, and asks for a stable agent ID. Press Enter to keep existing values. This setup option accepts local keys only. After saving, follow the wallet workflow in [SKILL.md](skills/openany/SKILL.md). For first-time use, run `openany-dev keys create --identity wallet --label agent-main -j` to register the account automatically, confirm the key was saved, then run `openany-dev auth wallet -j`. If you already have a key for the wallet, log in directly.
150
+ - `--wallet_connect wallet` prompts for the wallet private key using masked input, derives the address, and asks for a stable agent ID. Press Enter to keep existing values. This setup option accepts local keys only. After saving, follow the wallet workflow in [the setup guide](skills/openany/setup.md#wallet-login-and-api-key-management). For first-time use, run `openany-dev keys create --identity wallet --label agent-main -j` to register the account automatically, confirm the key was saved, then run `openany-dev auth wallet -j`. If you already have a key for the wallet, log in directly.
151
151
  - `--email_login email` prompts for an email address. After saving it, run `openany-dev auth email send` to send a verification code, then run `openany-dev auth email verify --code SIX_DIGITS` to log in.
152
152
 
153
153
  `openany-dev status_check wallet|email|api_key|payment` checks local configuration only. Use the literal names `wallet`, `email`, and `api_key` where applicable. The legacy `setup --scenario …` and `status --scenario …` forms still work, and the JSON `scenario` field retains its original value. `setup -j`, `setup --non-interactive`, non-terminal input, `setup --prepare`, and `setup --scenario payment` continue to check configuration without waiting for input or saving changes. Add `--prepare` to check an existing external-signing command. For top-up checks, specify `--identity wallet|email`. Configuration status reports only whether local settings are present. Login, key validity, and payment authorization require separate checks.
@@ -160,7 +160,7 @@ Wallet commands include `auth wallet` and `keys create|rotate --identity wallet
160
160
 
161
161
  Use `auth email send|verify|refresh|workspace` for email authentication and `keys remote list|get|create|revoke` to manage remote keys. To rotate an email account key, create a new key, switch callers to it, verify it works, and revoke the old key manually. The `OPENANY_DEV_API_KEY` environment variable takes precedence over the local key. Update the environment secret after rotation.
162
162
 
163
- Top-ups use `topups authorize → create → pay → get`. See [SKILL.md](skills/openany/SKILL.md) for the complete commands and external signature formats. Limits apply to the actual payment amount, including fees. Orders awaiting payment also count against the reserved amount. Each intent fixes the amount, destination, and network. If creation has an uncertain outcome, rerun with the original arguments and `--resume`. If payment submission has an uncertain outcome, query its status only. The CLI leaves repeat top-ups and increases to authorization limits to the caller.
163
+ Top-ups use `topups authorize → create → pay → get`. See [the top-up guide](skills/openany/topups.md) for the complete commands and external signature formats. Limits apply to the actual payment amount, including fees. Orders awaiting payment also count against the reserved amount. Each intent fixes the amount, destination, and network. If creation has an uncertain outcome, rerun with the original arguments and `--resume`. If payment submission has an uncertain outcome, query its status only. The CLI leaves repeat top-ups and increases to authorization limits to the caller.
164
164
 
165
165
  ## Output, persistence, and recovery
166
166
 
@@ -186,14 +186,14 @@ The backend signing origin must be `https://dev.openany.si`. Deploy the service
186
186
 
187
187
  ## Skill documentation maintenance
188
188
 
189
- `skills/openany/SKILL.md` is the source for the packaged skill and the website copies. After updating it, synchronize the website checkout and verify the result:
189
+ `SKILL.md`, `setup.md`, `calls.md`, and `topups.md` in `skills/openany` are the packaged English skill and the source for the website copies. After updating any of them, synchronize the website checkout and verify the result:
190
190
 
191
191
  ```bash
192
192
  npm run sync:skill -- ../openany-interface/openany-interface
193
193
  npm run sync:skill -- ../openany-interface/openany-interface --check
194
194
  ```
195
195
 
196
- The path must point to the `openany-web` project. The command validates that the skill uses the latest CLI release channel and updates `public/SKILL.md` and `docs/skills/openany/SKILL.md`. In the website checkout, run `npm run check:agent-docs` to verify that guides and client recipes also use the latest release channel without pinning a CLI version. Website builds run that check automatically. Commit both repositories together for a documentation release; these commands do not publish packages or deploy the website.
196
+ The path must point to the `openany-web` project. The command validates that the skill uses the latest CLI release channel and updates the entry and three guides under `public/` and `docs/skills/openany/`. In the website checkout, run `npm run check:agent-docs` to verify that guides and client recipes also use the latest release channel without pinning a CLI version. Website builds run that check automatically. Commit both repositories together for a documentation release; these commands do not publish packages or deploy the website.
197
197
 
198
198
  ### New email registration
199
199
 
@@ -261,7 +261,7 @@ openany-dev seller connections create --application APPLICATION_ID --operation c
261
261
 
262
262
  The dialog collects the label, base URL, authentication type, optional query/path
263
263
  parameter name, and a masked API key. It uses the key entered in the dialog,
264
- not `OPENANY_DEV_UPSTREAM_API_KEY`. The key is submitted to OpenAny without being
264
+ not `OPENANY_CONNECTION_API_KEY`. The key is submitted to OpenAny without being
265
265
  saved locally or printed. Cancellation or a five-minute timeout submits nothing.
266
266
  Invalid fields display a safe error and reopen the form for correction.
267
267
  `--gui` supports non-terminal invocation and JSON output on a desktop, but cannot
@@ -277,15 +277,15 @@ openany-dev seller connections create --application APPLICATION_ID --operation c
277
277
 
278
278
  Enter the connection label, base URL and authentication type (number or name).
279
279
  Query/path authentication also asks for the parameter name. If authentication
280
- requires a key, the CLI uses `OPENANY_DEV_UPSTREAM_API_KEY` when set, otherwise it
280
+ requires a key, the CLI uses `OPENANY_CONNECTION_API_KEY` when set, otherwise it
281
281
  prompts with hidden input. Ctrl-C or EOF cancels without creating a connection.
282
282
  `--application` and `--operation` remain required command-line parameters.
283
283
  Explicit `--file`/`--input`, `--stdin`, `-j`, `--non-interactive` and non-terminal
284
284
  input do not start the interactive form; supply JSON configuration in those modes.
285
285
 
286
286
  For scripted creation, create a non-secret connection configuration file containing `label`, `baseUrl`,
287
- `authType` and, where required, `authParamName`. Supply the upstream key using
288
- `OPENANY_DEV_UPSTREAM_API_KEY` or `--stdin`, never JSON or a command argument:
287
+ `authType` and, where required, `authParamName`. Supply the connection API key using
288
+ `OPENANY_CONNECTION_API_KEY` or `--stdin`, never JSON or a command argument:
289
289
 
290
290
  ```sh
291
291
  openany-dev seller connections create --application APPLICATION_ID --file connection.json --stdin --operation connection-create -j
@@ -305,14 +305,14 @@ For `models verify`, `request.path` must be an empty object `{}` when supplied,
305
305
  never a URL string such as `"/v1/chat/completions"` or a nonempty parameter map.
306
306
  The CLI rejects invalid values locally with `INVALID_INPUT` and
307
307
  `field: "request.path"`. The actual request path comes from the saved
308
- `price.upstreamPath[endpointIndex]`; `endpointIndex` is zero-based. Read the saved
309
- model first and use its current version, route ID and upstream revision:
308
+ `price.servicePath[endpointIndex]`; `endpointIndex` is zero-based. Read the saved
309
+ model first and use its current version, route ID and connection revision:
310
310
 
311
311
  ```json
312
312
  {
313
313
  "expectedVersion": "SAVED_MODEL_VERSION",
314
314
  "routeId": "SAVED_ROUTE_ID",
315
- "expectedUpstreamRevision": 1,
315
+ "expectedConnectionRevision": 1,
316
316
  "endpointIndex": 0,
317
317
  "request": {
318
318
  "path": {},
@@ -328,7 +328,7 @@ model first and use its current version, route ID and upstream revision:
328
328
 
329
329
  Replace the version, route ID, revision, endpoint index and test body with the
330
330
  saved configuration and authorized test inputs. Model verification uses the saved
331
- upstream model identity. This empty-path restriction applies only to models;
331
+ service model identity. This empty-path restriction applies only to models;
332
332
  `apis verify` can use a path parameter object required by its saved API template.
333
333
 
334
334
  Use `apis` instead of `models` for API resources. Every write requires a stable
@@ -348,7 +348,7 @@ use the correct account and supplier.
348
348
  Supplier admission remains required. Once admitted, configure and verify each
349
349
  resource, then publish directly without a separate human review. Model publication
350
350
  uses `expectedVersion` and `verificationIds`; API publication uses `expectedRevision`,
351
- `expectedUpstreamRevision`, and `verificationId`. Authorized edits use current
351
+ `expectedConnectionRevision`, and `verificationId`. Authorized edits use current
352
352
  versions and no longer require review withdrawal. Read activation and runtime
353
353
  synchronization separately. Historical review queries remain available.
354
354
 
@@ -381,13 +381,13 @@ method/path cannot be silently overridden. OpenAPI parameters are not guessed
381
381
  into gateway mappings or pricing. `charge_condition:null` explicitly accepts the
382
382
  server's HTTP-success default.
383
383
 
384
- Bindings use `{schemaVersion:1,items:[{itemId,upstreamKeyId}]}` for APIs or
385
- `{schemaVersion:1,items:[{itemId,routes:[{index,upstreamKeyId}]}]}` for models. Files
384
+ Bindings use `{schemaVersion:1,items:[{itemId,connectionId}]}` for APIs or
385
+ `{schemaVersion:1,items:[{itemId,routes:[{index,connectionId}]}]}` for models. Files
386
386
  must contain only items in that batch. Templates under
387
387
  `skills/openany-provider/templates/` are intentionally incomplete, not quotes or
388
388
  production defaults. Ask for actual pricing and authorization before use.
389
389
 
390
- Preview does not create resources or call upstreams. Run/resume only creates
390
+ Preview does not create resources or call services. Run/resume only creates
391
391
  drafts. Missing connections are local `waiting_connection` items; other items
392
392
  continue. Prepare or select an owned connection, then resume with its binding.
393
393
  Missing credentials never imply `authType=none`. Summaries distinguish readiness,
@@ -400,7 +400,7 @@ submission remain separate, authorized, per-resource steps.
400
400
  The local batch binds the account and supplier and uses the existing restricted
401
401
  credentials file (0600). Secret-bearing documents are rejected before storage.
402
402
  CLI tests use synthetic credentials and mocked HTTP; they do not prove deployment
403
- readiness, mailbox delivery, real upstream compatibility or administrator review.
403
+ readiness, mailbox delivery, real service compatibility or administrator review.
404
404
 
405
405
  Sync the complete Provider Skill into the website with:
406
406
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openany-cli-dev",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "OpenAny command-line client for internal dev testing",
5
5
  "type": "module",
6
6
  "engines": {
@@ -1,353 +1,34 @@
1
1
  ---
2
2
  name: openany
3
3
  description: >-
4
- Use when the user needs to discover and call model, data, or tool APIs through OpenAny, check balances and call records, or manage wallet login, email login, API keys, and top-ups.
4
+ Use when the user needs to discover and call model, data, or tool APIs through OpenAny, check balances and call records, submit seller reviews, or manage wallet login, email login, API keys, and top-ups.
5
5
  metadata:
6
6
  cli-channel: "latest"
7
7
  ---
8
8
 
9
- # OpenAny CLI
9
+ # OpenAny quick start
10
10
 
11
- OpenAny CLI discovers and calls model, data, and tool APIs, and manages accounts, API keys, and top-ups. Use the latest published OpenAny CLI with this skill. Node.js >=22 is required.
11
+ Use the latest OpenAny CLI with Node.js >=22. Install or update it with `npm install -g openany-cli-dev@latest --registry=https://registry.npmjs.org/`.
12
12
 
13
- Prefer a tool the user has specified or an appropriate dedicated tool that is already available. When operating through OpenAny, stay within the purpose and budget authorized by the user.
13
+ Prefer a tool the user has specified or an appropriate dedicated tool already available. Stay within the authorized task and budget.
14
14
 
15
- The backend and signing service use **https://dev.openany.si**; model requests use **https://api-dev.openany.si** with the path and query from the selected catalog `curlExample`. Do not execute the curl text in a shell. There is no command-line origin override.
15
+ ## Choose the guide for the current task
16
16
 
17
- The CLI uses API keys and shared-balance billing for resource calls. Its x402 workflow tops up that balance; it does not implement direct x402 payment for an individual API request. Separate x402 resources must be evaluated under their own published contracts, outside this CLI workflow. Authentication and top-up availability also depend on the deployed service configuration; local configuration checks do not prove those services are enabled.
17
+ Read only the guide that applies. Follow a second guide when the task reaches a step that needs it, such as configuring a missing key before an API call.
18
18
 
19
- ## Email code input when no mailbox tool is available
19
+ - [Setup and account access](./setup.md) for installation, credentials, wallet or email login, API keys, logout, and account recovery.
20
+ - [Model and API calls](./calls.md) for public browsing, pricing, previews, execution, asynchronous results, call history, and seller reviews.
21
+ - [Balances and top-ups](./topups.md) for balance checks, low-balance guidance, fees, and manual or authorized automatic top-ups.
20
22
 
21
- For an authorized OpenAny email login, first use an available, authorized mailbox tool. If none is connected or it cannot read the current code, open a text-input form using the host's user-input tool (for example, `request_user_input_async`). Prompt: “Enter the six-digit code sent to your OpenAny login email. It will be passed to the Agent to complete this login. Do not enter your email password.” This is an explicit exception for the current OpenAny email login code; it does not permit collecting passwords, API keys, private keys, or other credentials in forms.
23
+ Resolve relative links against the original Skill URL when reading it on the web. If you only have a local copy of this entry and the guides are missing, fetch them from the website for the selected environment. Keep the guide URL in that environment.
22
24
 
23
- Treat the response as a string, trim surrounding whitespace, and require exactly six ASCII digits; preserve leading zeros. If invalid, reopen the form without repeating the entered value. After any required browser approval, run `openany-dev auth email verify --code SIX_DIGITS -j` with the submitted code. Do not echo the code in replies, write it to documentation, or retain it for later use. An ordinary input form returns the code to the Agent; do not describe it as a private native credential dialog. If forms are unavailable, have the user verify in their own terminal and report completion. Do not resend merely because a mailbox tool is unavailable; reuse the current challenge, and only request a new code after expiry. A submitted form is not proof of successful login: check the CLI result.
25
+ ## Before using OpenAny
24
26
 
25
- ## Log out or switch accounts
27
+ - Select the environment from the task's published documentation and endpoint. Check the CLI's support before any network command, and keep credentials and requests scoped to that environment. See [environment isolation](./calls.md#environment-isolation) for API requests the CLI cannot support.
28
+ - Public catalog browsing and model dry-runs require no key. Keep secrets out of chat, logs, and command arguments. Follow the setup guide for secure input and the email verification code flow.
29
+ - Resource charges use the API key's shared balance. The CLI's x402 workflow funds that balance. Evaluate separate x402 resources under their own published contracts.
30
+ - Report verified outcomes and keep the original request, task, or top-up ID. Check the original record when an outcome is uncertain.
26
31
 
27
- When the user requests logout or account switching, explain that this clears **all accounts in the current local configuration**, then run `openany-dev logout -j`. First let any ongoing login, registration, or payment command finish or cancel it safely; do not start concurrent account operations. The CLI moves the complete credentials file to a uniquely named backup in the same configuration directory, retaining restricted permissions. It does not revoke server-side keys, sessions, or accounts, or cancel payments. Always show the returned `backupPath`; if null, report that no local configuration file existed. The backup contains credentials: never read it into chat, upload it, or display its contents.
32
+ ## Seller Reviews
28
33
 
29
- Check `environmentOverrides`: if nonempty, show variable names only and ask the user to remove them from the actual calling environment before switching accounts. Do not claim complete logout while they remain. Once logout is complete, offer API Key, wallet, and email setup using a selection form when available, with text choices as fallback; use the existing setup flow for the selected method. If the user requested logout only, stop after reporting the result. Check CLI help for `logout` support and update if needed; never substitute unbacked file deletion.
30
-
31
- ## Open authorization links automatically
32
-
33
- Whenever an authorized flow returns a browser approval or verification URL (including wallet registration and email `verificationUrl`), display the exact complete URL as a clickable link, preserving its query and `#` fragment, then immediately use an available browser-opening tool to open it visibly for the user. Do not stop at displaying the link or ask the user to open it when the tool is available. If no browser tool is available or opening fails, explain that limitation and ask the user to open the displayed link manually. Opening a page does not approve registration, login, or payment: the user must review and perform approval and human verification themselves. Keep any waiting CLI process running and continue only after the required confirmation or CLI result. This rule takes precedence over manual-link-opening wording below.
34
-
35
- ## Native credential setup
36
-
37
- On macOS or Windows desktops, prefer `openany-dev setup --api_key api_key --gui -j` or `openany-dev setup --wallet_connect wallet --gui -j` for the chosen credential type. Each opens an independent native dialog. Let the user fill it in. Never read or screenshot the credential field. Wallet setup requires confirmation of the locally derived address. Only status is returned. Cancellation or a five-minute timeout saves nothing.
38
-
39
- When supported, this flow takes precedence over the terminal-only walkthroughs below. `--gui -j` explicitly allows saving without a TTY. Update an older CLI and check help. If native UI is unavailable, use the terminal walkthrough. Environment overrides still apply. Verify the saved status. Configuration does not authorize login or payment.
40
-
41
-
42
- ## Preflight Checks
43
-
44
- For actual model, data, or tool execution, use scenario A below; only an API key is required. Public catalog browsing and `models run --dry-run` are exempt from these credential checks and can precede configuration.
45
-
46
- 1. If required credentials or local settings are missing, follow **Missing Configuration: Required User Guidance** below. Explain the exact terminal steps and explicitly warn against sending sensitive information in any AI/model conversation; ask the user to configure locally and confirm completion, never to supply secret values in chat. If tools or authorization details are missing, explain what is needed and request only the relevant connection or authorization. Missing CLI-managed login sessions or payment policies can be established within existing authorization using the login and Authorized Top-Ups steps below; do not ask the user to edit the credentials file.
47
- 2. If configuration status is unknown, run one local check: `openany-dev status --scenario call -j`. Use `configured` and `missing` to determine whether all required settings are present. Exit code 0 means the check completed; subsequent requests must still verify that the configuration works.
48
- 3. If the API key is missing, pause execution requests. Explicit public catalog browsing and `models run --dry-run` may proceed without a key. If the user already has a key, guide them through `openany-dev setup --scenario call` in their own terminal; otherwise, follow the wallet/email login and key-creation flow below within their authorization. Use only credentials configured or explicitly designated by the user through an authorized secure mechanism. Do not scan repositories, `.env*` files, user directories, or credential stores, and do not send invalid keys as a test. If running unattended and configuration cannot be obtained, record the missing setting names without values and end the run.
49
- 4. Once configuration is complete, reuse it to check the balance and make calls. On a 401 from an API-key-authenticated request, pause and ask the user to check that key. For an email-session 401, use the explicit refresh and recovery steps below. Keep the original authentication method and service URL.
50
-
51
- ### Missing Configuration: Required User Guidance
52
-
53
- Whenever required configuration is missing, the response to the user **must** include all of the following, in the user's language. A bare variable name, a bare `setup` command, or "configure your credentials" is insufficient.
54
-
55
- For wallet/email login and key creation, apply this guidance before authentication, even when the user started from AGENT.md or AUTH.md. You must use interactive setup; do not substitute instructions to export private keys or write secrets into `~/.zshrc`, other shell profiles, or `.env` files. Ask which login method to use only if the user has not already chosen one.
56
-
57
- 1. State the missing setting names and why they are needed for this task. Request only the applicable scenario; ordinary API calls do not require wallet or email setup.
58
- 2. Give the exact interactive command from the configuration walkthrough below, explain each input in order, and say to run it in the user's own terminal on the machine/account where the CLI will be used. If the CLI is absent, include the installation command from this skill first. Do not run a hidden-input wizard on the user's behalf and then ask them to send you its answers.
59
- 3. Explicitly remind the user: **Do not submit API keys, wallet private keys, seed phrases, passwords, access/refresh tokens, cookies, or credentials file contents in any AI/model conversation, including this chat, screenshots, or attachments.** API keys and private keys belong only in the CLI's hidden terminal prompts or an already authorized secure secret-injection mechanism. Email setup requires only an email address, never an email password. If the user offers to send a secret, redirect them to local configuration without requesting or repeating it.
60
- 4. Explain that setup saves locally to `~/.config/openany-dev/credentials.json` (or `OPENANY_DEV_CONFIG_DIR`), using the existing directory 0700/file 0600 permissions. Do not ask the user to open, print, edit, or upload that file. Setup does not log in or authorize payments.
61
- 5. Ask the user to reply only that configuration is complete. Then rerun the relevant `openany-dev status --scenario SCENARIO -j` check in the CLI's execution environment. Inspect `configured` and `missing`; do not rely on exit code 0 alone or treat a local check as proof of login, key validity, or payment permission. If settings are still missing, explain those names and the next local step without asking for secret values. Nonempty environment variables override local values; if `environmentOverrides` is reported, explain the precedence without requesting variable values.
62
-
63
- Example response for a missing API key (translate to the user's language):
64
-
65
- > OpenAny is missing an API key for this request. In your own terminal, run `openany-dev setup --scenario call`. Enter a key name such as `main`, enter the API key at the hidden prompt, and answer `y` to make it the current key. The CLI saves it locally in `~/.config/openany-dev/credentials.json` with file permission 0600 and directory permission 0700. Do not send API keys, wallet private keys, seed phrases, passwords, tokens, cookies, or the credentials file in this or any other AI/model chat, including screenshots or attachments. When finished, reply only "configured"; I will check with `openany-dev status --scenario call -j` before continuing. Setup only saves configuration and does not log in or authorize payments.
66
-
67
- Example response after the user selects wallet login and authorizes login and key creation, with wallet settings missing (translate to the user's language):
68
-
69
- > The core settings required for wallet login are not configured yet. In your own terminal on the same machine/account where OpenAny runs, execute `openany-dev setup --scenario wallet` to complete configuration. Enter the private key at the hidden prompt; the CLI derives and displays your wallet address automatically. Then enter a stable Agent ID such as `agent-main`, using 6–128 letters, digits, dots, underscores, colons, or hyphens, and keep it for later use. Setup saves locally to `~/.config/openany-dev/credentials.json` with directory 0700/file 0600 permissions. Do not send private keys, seed phrases, API keys, passwords, tokens, cookies, or the credentials file in any AI/model chat, screenshot, or attachment. Reply only "configured" when finished. I will run `openany-dev status --scenario wallet -j`; once it reports configured with nothing missing, I will follow the wallet flow under your existing authorization: for a first-time wallet without a key, run `openany-dev keys create --identity wallet --label agent-main -j` to start registration. If the CLI requires browser approval, I will share its link and keep the command running while you verify. I will then run `openany-dev auth wallet -j` after the key is saved. If you already have a key for this wallet, I will reuse it and log in directly without creating another key. The generated key is saved locally; `keys list` shows only metadata, not its value. Setup alone does not log in, create keys, or authorize payments.
70
-
71
- If settings remain missing after the user's confirmation, verify that the user and agent are using the same execution environment and configuration directory without reading or requesting secret values. Do not treat configuration on the user's laptop as configuration in a separate agent runtime.
72
-
73
- If the user does not have an API key yet, explain that setup saves an existing key and cannot issue one. Offer the wallet or email login and key-creation flow below within the user's authorization; those commands save the generated key locally without requiring the user to paste it into chat.
74
-
75
- When explaining check results, report only what was actually checked. Ordinary API calls do not require a wallet, email address, service URL, or agent ID.
76
-
77
- **Browsing the public catalog only:** If the user explicitly wants only to browse the catalog without making paid calls, use `discover/collections/inspect --public` or `models prices/playgrounds/parameters/examples --public` without an API key. `models run --dry-run` also needs no key: it only reads the public catalog and previews a request; it never checks balance or executes a model. Complete credential configuration before actual execution; public discovery and dry-run may happen first.
78
-
79
- ## Installation and Configuration Scenarios
80
-
81
- Install or update to the latest published CLI through npm to make the global `openany-dev` command available. Use the npm `latest` release channel instead of a fixed version:
82
-
83
- ```bash
84
- npm install -g openany-cli-dev@latest --registry=https://registry.npmjs.org/
85
- openany-dev --version
86
- openany-dev --help
87
- ```
88
-
89
- If credentials are known to be missing, ask for configuration before actual execution; public browsing and dry-run may happen first. If the CLI is also missing, explain the installation requirement at the same time. Do not require a specific numeric CLI version. Use `openany-dev --version` to report the installed version and `openany-dev --help` to check available commands. If an installed CLI lacks a documented command or option, update it with the command above and check again before proceeding; do not assume that installation alone verifies API access. Make all API calls through the CLI so that configuration checks and call validation apply.
90
-
91
- Choose the configuration scenario for the task, reuse existing settings, and supply only missing items:
92
-
93
- | Scenario | Ask the user to provide or authorize | Local check |
94
- | --- | --- | --- |
95
- | A. Model, data, and tool calls only | `OPENANY_DEV_API_KEY`, or the current key saved in the CLI | `openany-dev status --scenario call -j` |
96
- | B. Autonomous top-ups | A + target identity (wallet/email) + payment wallet address, private key or authorized signing tool + network, per-payment limit, total limit, scope, and expiration; log in using C/D and record existing approval with `topups authorize` | `openany-dev status --scenario payment --identity wallet --scope TASK_SCOPE -j` (use email for email identity) |
97
- | C. Create or rotate keys with a wallet | `OPENANY_DEV_WALLET_ADDRESS`, `OPENANY_DEV_WALLET_PRIVATE_KEY` or an authorized signing tool, and a stable `OPENANY_DEV_AGENT_ID` | `openany-dev status --scenario wallet -j` |
98
- | D. Manage keys with email login | `OPENANY_DEV_EMAIL` and authorized access to that mailbox; select the target if there are multiple workspaces | `openany-dev status --scenario email -j` |
99
-
100
- Store private keys and API keys using interactive `openany-dev setup` or the runtime's secure credential settings (secrets), never in chat or command-line arguments. Access email through an email tool already connected and authorized for the agent; the CLI does not need an email password. When using an existing external signing tool outside setup, add `--prepare` to configuration check commands; a local private key is not required. Before execution, still confirm that the signing tool is available and authorized.
101
-
102
- Wallet private key formats: EVM uses a 32-byte hexadecimal key with or without a `0x` prefix; Solana uses a Base58-encoded 64-byte secret key. The CLI verifies that the address matches the private key. Use a stable agent ID supplied by the user or runtime, and keep it consistent across subsequent calls.
103
-
104
- ### Interactive Configuration Walkthrough
105
-
106
- Give the relevant row as an ordered walkthrough, together with the mandatory sensitive-information warning above. `openany-dev setup` also offers a menu: 1 for API calls, 2 for wallet, and 3 for email.
107
-
108
- | Needed configuration | Command in the user's terminal | Inputs in order | Check after the user confirms completion |
109
- | --- | --- | --- | --- |
110
- | API calls | `openany-dev setup --scenario call` | Enter a key name (default `main` or the current key label); enter the API key at the hidden prompt; answer `y` to activate it for subsequent calls. | `openany-dev status --scenario call -j` |
111
- | Wallet | `openany-dev setup --scenario wallet` | Enter the private key at the hidden prompt; the CLI derives and displays the wallet address automatically; enter a stable Agent ID of 6–128 letters, digits, dots, underscores, colons, or hyphens, and keep using that ID. Setup offers no external-signing option. | `openany-dev status --scenario wallet -j` |
112
- | Email | `openany-dev setup --scenario email` | Enter the email address only; no password or verification code is requested during setup. Saving the address does not log in. | `openany-dev status --scenario email -j` |
113
-
114
- Setup only saves local configuration. It does not log in, send email, create keys, authorize top-ups, or submit payments. Its result includes the saved path, status, next commands, and names of environment variables overriding the saved values. When login is needed, follow Wallet Login and API Key Management below (first-time wallets create a key before login), or use `auth email send` followed by `auth email verify`.
115
-
116
- For agents and scripts, prefer `status --scenario SCENARIO -j`. `setup -j`, `setup --non-interactive`, setup without a TTY, `setup --prepare`, and `setup --scenario payment` remain read-only checks and never prompt or save. An interactive setup must not be used as a passive readiness check.
117
-
118
- ### Save an Existing Key
119
-
120
- `OPENANY_DEV_API_KEY` in the environment takes precedence over the current local key. You can also save a key from a securely injected environment variable:
121
-
122
- ```bash
123
- openany-dev keys add --label main --activate
124
- openany-dev keys list -j
125
- ```
126
-
127
- If the environment variable is not set, enter the key with hidden input in an interactive terminal. For unattended use, pass a secret through controlled standard input: `openany-dev keys add --label main --activate --stdin`. Never include a plaintext key in command text.
128
-
129
- Local configuration is stored at `~/.config/openany-dev/credentials.json`, with existing file permissions 0600 and directory permissions 0700. The file is not additionally encrypted and can include a wallet private key saved by setup; do not upload or print it. `keys list` shows only labels and metadata; `keys activate --label NAME` switches the local key, and `keys remove --label NAME` removes only the local record.
130
-
131
- ### Report Configuration Completion
132
-
133
- **Amount formatting rule (internal; do not print):** The CLI's `balance` response preserves `availableMicroUsd` and adds `availableUsd` (an exact decimal USD string) and `availableUsdFormatted` (the same value prefixed with `$`). Display `availableUsdFormatted` verbatim alongside the original `availableMicroUsd` from that same response. Do not recalculate, round, move the decimal point, or add another dollar sign. The CLI uses integer arithmetic with `1 USD = 1,000,000 microUSD`, preserving two to six fractional digits without precision loss. Use raw microUSD values for balance thresholds and budget decisions. If an older CLI does not return the display fields, update it using this skill's installation steps and query the balance again; if the fields remain unavailable, show only the raw microUSD amount and explain that the USD display is unavailable. Never fill in a dollar amount yourself. For other commands that return only raw microUSD amounts, preserve the returned unit instead of inventing USD display fields; values already denominated in USD must not be converted again.
134
-
135
- After setup and the authorized connection checks, the final user-facing completion reply MUST include both the verified status/balance and a separate **Usage example** section in the user's language. Distinguish configured credentials from a successfully executed business call.
136
-
137
- **Required content, not an interchangeable suggestion:** The Usage example MUST explain this complete path: search for `bitcoin` to find the Bitcoin price; if no relevant API appears, browse **Finance** or **Crypto & DeFi**; choose a relevant data platform, such as **BlockRun if listed**; review the concrete API's description before calling it. Preserve these steps when translating. Include this example regardless of whether the balance is below, equal to, or above $5; only the balance/recharge wording is conditional on observed facts.
138
-
139
- Do not replace this example with the user's earlier task, model integration (such as SiliconFlow/DeepSeek), a generic command list, or a question asking what to try next. Context-specific next steps may be appended only after the required example. Explaining the example does not authorize executing it; do not make a Bitcoin API call merely to complete onboarding.
140
-
141
- **Output format:** Render the Usage example as ordinary prose, not a fenced code block or shell-command tutorial. For an English reply, use the supplied Usage example paragraph verbatim; for another language, translate that paragraph faithfully without omitting any step. Do not output `openany-dev discover`, `openany-dev inspect`, `openany-dev run`, placeholder API IDs, or request JSON in the configuration-completion example. The execution reference later in this document is for performing a separately requested task, not text to copy into the completion reply. A command sequence alone is a failed completion reply even if it mentions Bitcoin.
142
-
143
- Before sending the completion reply, check that it contains `bitcoin`, both category options, the conditional BlockRun example, and the instruction to review the API description before calling. If any element is missing, add it before responding.
144
-
145
- The 5 USD threshold is a reminder, not a minimum usable balance or a minimum deposit. Never say that paid calls require a recharge solely because the balance is below 5 USD. Compare the available balance with the selected request's current price or required reservation and the user's budget. If cost is unknown, check pricing first rather than claiming insufficient funds. Free calls and affordable paid calls may proceed within existing authorization and access limits.
146
-
147
- Balance wording below assumes successful checks and a balance below $5. The Usage example is mandatory at every balance:
148
-
149
- > Your OpenAny configuration and balance have been verified. Your available balance is below $5.00. You can top up through the dashboard or let me know that you would like to authorize automatic top-ups.
150
- >
151
- > **Usage example:**
152
- >
153
- > To look up the Bitcoin price, start by searching for `bitcoin`. If no relevant API appears, try browsing the Finance or Crypto & DeFi category. Select a relevant data platform, such as BlockRun if listed, then carefully review the API description before calling it.
154
-
155
- Replace the amounts and verification status with observed facts. Do not present optional recharge as a prerequisite for finishing setup or using affordable calls.
156
-
157
- ## Call Data and Tool APIs
158
-
159
- Execution reference only; do not copy this command block into the configuration-completion reply. Inspect the concrete API first, then construct `openany-dev run` and its arguments only from its actual schema. Do not assume that an API accepts `limit`.
160
-
161
- ```bash
162
- openany-dev balance -j
163
- openany-dev discover -q "Get hot search data" -l 10 -j
164
- openany-dev inspect --id API_ID -j
165
- ```
166
-
167
- Follow this sequence: check the balance → search for an API → inspect its definition → make the call. Replace `API_ID` in the examples with an ID returned by the current search. Use the latest API definition returned by `inspect`, including pricing, required parameters, and version. If multiple APIs match, ask the user to confirm the platform, provider, or intended use.
168
-
169
- Website capability pages group concrete API offerings from providers. Select an authorized offering, then use its API ID with `inspect` and `run`; a capability key, capability ID, or collection ID is not an executable API ID. The CLI currently discovers concrete APIs, not capability groups. Inspect the selected offering's own parameters, revision, and price; providers in the same group can have different contracts. Do not substitute a provider without authorization.
170
-
171
- - `balance` checks the balance using the current API key and supports keys created through wallet or email login.
172
- - `discover` supports `--provider`, `--data-platform`, `--category`, `--method`, and `--cursor`; `collections` lists catalog collections.
173
- - Before calling, confirm the request method, path, input type, required fields, and cost, and stay within the current task's authorization and budget. After each balance check, follow **Low-Balance Guidance** below; apply the execution rule in Authorized Top-Ups when autonomous top-ups are already authorized. If the balance cannot cover the requested call, explain that recharge is needed before proceeding. Wallet registration follows the authorized onboarding flow below; reuse existing registration and key-creation authorization without asking again.
174
- - `run` automatically reloads the API definition, validates parameters, checks the balance, and submits the request. `--path/--query/--headers` accept JSON. Use `-i JSON` or `-f FILE` for the request body. If the API definition is incompatible with the CLI, such as a GET request that requires a body, report the error instead of bypassing CLI validation to send the request.
175
- - `-j` outputs JSON; `-o FILE` writes results to a file without overwriting an existing file. Show the user the data actually returned by the API and retain `requestId`. Explain catalog query, balance query, and authentication errors separately from business call results.
176
- - If `run -j` returns HTTP 202 with `body.task_id`, the task is only accepted. Follow **Deliver Asynchronous API Results** before sending a completion reply. If submission is uncertain and no task ID is available, inspect call records before considering a replay of a request that may already have been charged.
177
-
178
- ```bash
179
- openany-dev calls list --limit 20 -j
180
- openany-dev calls get --id REQUEST_ID -j
181
- ```
182
-
183
- `calls list/get` queries persisted model and data/tool API usage for the current API key when the backend includes unified usage-call support. Older backends exclude model calls; updating the CLI alone does not change that. An empty result or missing record does not prove a request was not executed or charged; keep uncertain requests pending rather than automatically repeating them.
184
-
185
- Record filters include `--api-id`, `--status success|failed`, `--from/--to` (UTC ISO format with milliseconds), and `--cursor`. `--review-required` is unsupported because usage logs have no review state; the CLI rejects it before making a request. Do not guess status aliases such as `settled`, `succeeded`, `ok`, or `pending`.
186
-
187
- Replace `REQUEST_ID` with the real request ID. Model trace IDs are supported; canonical UUIDs match their 32-hex form as well, while other opaque IDs match exactly. `usageType` distinguishes `model` from `api`; model rows have `apiId: null`, a model name and the recorded provider. `chargedCostMicroUsd` is the persisted per-row charge in micro-USD; monthly usage is an aggregate, not proof of any individual charge. Unknown review or settlement metadata stays unknown. Lists default to seven days, with a maximum 31-day explicit range; detail queries are independent of that window. Old API-only cursors become invalid after the backend update; restart listing without a cursor. Never bypass key scope or automatically retry a possibly charged model request because its log is missing.
188
-
189
- ### Deliver Asynchronous API Results
190
-
191
- 1. Save the original task ID and request ID. With the original API key and environment, use `openany-dev tasks wait --id TASK_ID --timeout-seconds 120 -j` to poll or `openany-dev tasks get --id TASK_ID -j` for one lookup. On `timedOut: true`, resume polling the same task within the published task deadline. These are read-only operations; never resubmit a paid call to retrieve its result. If you cannot continue waiting, report the last known status and task ID and say the result has not been delivered.
192
- 2. When `status` is `completed`, read `result` and `artifacts`. For each requested file, download it before `result_expires_at` with an authenticated `GET /v1/agent-api-tasks/{task_id}/artifacts/{artifact_id}` on the original gateway, using the returned IDs and the original buyer key. The CLI task commands return file metadata rather than file contents; use a scoped HTTP client for the download with the original key loaded securely, and disable redirects. Verify HTTP success, readability, and the returned content type and size when supplied.
193
- 3. **Deliver the output in the final reply.** Include the requested content from `result` and attach or link each requested file to a copy the user can open. For large inline results, save the full output to a user-accessible file and link it. A task ID, artifact ID, authenticated gateway URL or success message alone does not deliver the output. Include the task ID and request ID for reference. If an expected result is absent, expired or cannot be retrieved, give the user any available output and clearly identify what could not be delivered. On `failed` or `timed_out`, report the actual status and any `failure_code`. Report billing separately; an unavailable billing record must not delay available output.
194
-
195
- ### Example: Find a Bitcoin Price API
196
-
197
- 1. Start with the user's keyword: `openany-dev discover -q "bitcoin price" -l 10 -j`. An empty successful result does not prove that OpenAny lacks a Bitcoin price API; authentication or network errors must be handled separately.
198
- 2. If no relevant result appears, browse [the API catalog](https://dev.openany.si/apis) under **Finance** or **Crypto & DeFi**. Look for relevant data platforms/providers, for example **BlockRun** if present in the current category listing. Treat the platform as a candidate, not a guarantee that it offers the required price operation.
199
- 3. Open that platform's API list and look for a current Bitcoin/USD price operation. For CLI browsing, use `openany-dev collections -j` to read current collection metadata, then `openany-dev discover --data-platform "PLATFORM_FROM_CATALOG" -l 10 -j`, replacing the placeholder with the exact catalog value. Display names are not necessarily `--provider` IDs. Do not keep the failed keyword filter when browsing the platform's APIs. These are alternative browsing steps, not commands to execute as a batch. Category/platform browsing may replace a keyword recovery step; count catalog browsing requests against the same discovery recovery budget rather than starting a new allowance, and stop for clarification when exhausted.
200
- 4. Select a concrete executable API ID from the current listing and run `openany-dev inspect --id API_ID -j`. Verify that it returns the intended Bitcoin asset's price in USD, not a similarly named token, a historical series, or an unrelated operation. Read its required parameters, access requirements, current price and revision; do not invent a BlockRun endpoint or assume all providers use CoinGecko parameters.
201
- 5. Only after selecting a suitable API, construct `openany-dev run` from that API's inspected schema within the user's authorization and budget. Report the actual result, source, unit and request ID. If no suitable API is found, report the searches/categories checked and ask for clarification rather than fabricating an endpoint or calling every candidate.
202
-
203
- ## Calling Models from Curl Examples
204
-
205
- 1. Run `openany-dev models examples --model MODEL --public -j`. Read the request templates, provider names, example IDs, path parameters and per-example errors.
206
- 2. Optionally choose `--provider PROVIDER` to force provider routing. Choose `--example EXAMPLE_ID` when multiple examples remain; provider selection is not required if an example is selected. Never execute all examples as a batch. Copy IDs from the current listing; refresh after a sample changes.
207
- 3. Save the selected `request.json` template as `input.json` and supply the complete desired body, including `model` (unless the URL explicitly binds `{model}`). Do not assume example prompts/defaults are merged. Omit `route.provider` for server-side automatic routing. JSON and image-edit multipart requests only inject the provider when `--provider` is explicit. Otherwise provider placeholders are removed, while concrete input providers are preserved. Other route fields remain unchanged. A conflicting concrete model/provider is an error.
208
- 4. Preview, then execute only within the user's authorized scope:
209
-
210
- ```bash
211
- openany-dev models run --model MODEL --provider PROVIDER --example CREATE_EXAMPLE_ID -f input.json --dry-run
212
- openany-dev models run --model MODEL --provider PROVIDER --example CREATE_EXAMPLE_ID -f input.json
213
- openany-dev models run --model MODEL --provider PROVIDER --example QUERY_EXAMPLE_ID --path '{"task_id":"ACTUAL_TASK_ID"}'
214
- ```
215
-
216
- Dry-run needs no key and sends no model or balance request. Execution needs an API key. POST checks balance; GET task queries do not. Use the returned service response to obtain the task ID; the CLI does not infer response fields or automatically poll, retry, or download generated videos. Query templates must declare `{task_id}`; `YOUR_TASK_ID` is rejected until the catalog example is corrected.
217
-
218
- Multipart image edits (`/v1/images/edit` or `/v1/images/edits`) use explicit `--attach FIELD=FILE`; repeat the flag for multiple files. Never read example file paths. Supply scalar fields in the input JSON; arrays become repeated fields, and `route` is a JSON object. Audio transcription is unsupported and must not be attempted.
219
-
220
- `operations` and `parameters` are not execution prerequisites. `models parameters` remains informational; do not use `--protocol` or `--mode` with `models run`. `--endpoint` only checks the chosen example path. Invalid JSON, dangling continuations, unknown options, unresolved placeholders and conflicting model/provider values fail explicitly; do not repair or bypass them. Request paths and query parameters come from the selected examples; redirects are not followed even when an example includes `--location`. Preserve service errors and request IDs; uncertain POST outcomes must not be retried automatically.
221
-
222
- ## Wallet Login and API Key Management
223
-
224
- After completing configuration for scenario C, choose the flow for the configured wallet. Use `openany-dev keys list -j` to inspect local labels and metadata, together with the user's confirmed account/key information. An unrelated key, an imported key without wallet metadata, or an environment override does not establish that a key belongs to this wallet. An empty local list does not prove the wallet has never registered; ask if its account/key history is unclear.
225
-
226
- **First-time wallet without a key.** After the user authorizes registration and key creation, start one request:
227
-
228
- ```bash
229
- openany-dev keys create --identity wallet --label agent-main -j
230
- ```
231
-
232
- The backend verifies the signature and checks the signing wallet's official USDC on Base mainnet for EVM addresses or Solana mainnet for Solana addresses. This uses on-chain funds; the OpenAny API credit balance shown by `openany-dev balance` is separate.
233
-
234
- - **More than 10 USDC:** the wallet qualifies for automatic verification. Wait for the CLI to confirm that the key was saved.
235
- - **10 USDC or less, including exactly 10 USDC:** explain the threshold and offer the browser approval link. The user can continue without funding the wallet.
236
- - **Balance lookup unavailable:** explain that OpenAny could not read the balance. Use the same browser approval flow; the wallet's balance is unknown.
237
-
238
- When approval is required, keep the original CLI command running. Even with `-j`, the reason and one-time URL appear on stderr while the command waits. If you run the CLI for the user, promptly show them that exact link, including its fragment. Ask them to open it in their browser, check the wallet address and Agent ID, click **Approve registration**, and complete Turnstile. The CLI polls automatically and saves the key after approval. If the CLI reports `AUTHORIZATION_EXPIRED`, start a fresh request with the same wallet and Agent ID. For an uncertain submission, follow **Errors and Recovery** before retrying.
239
-
240
- Only after the CLI confirms the key is saved, log in:
241
-
242
- ```bash
243
- openany-dev auth wallet -j
244
- ```
245
-
246
- **Existing key for this wallet:** reuse the key and log in directly:
247
-
248
- ```bash
249
- openany-dev auth wallet -j
250
- ```
251
-
252
- Do not create or rotate a key just to log in. Keep the configured wallet and stable Agent ID unchanged. Do not treat a login failure or generic 401 as proof that the wallet is unregistered. If key creation returns a recovery file, follow Errors and Recovery before login; if the outcome is uncertain, resolve it before creating again. Do not change the label or Agent ID to bypass an existing-key conflict.
253
-
254
- Key rotation is a separate, explicitly authorized operation:
255
-
256
- ```bash
257
- openany-dev keys rotate --identity wallet --label agent-next --expected-key-id CURRENT_KEY_ID -j
258
- ```
259
-
260
- The CLI retrieves the message to sign, validates the service domain, identity, operation, and expiration, then signs it. Preserve the full original title and body of the signing message returned by the service. After saving a new key, the command outputs only metadata.
261
-
262
- When using an external signing tool, add `--prepare` to the commands above to obtain the message to sign. Sign it with an authorized tool, then submit it using the same command with `--challenge-id ID --signature-file FILE`. The signature file must contain the raw signature text and correspond to the challenge ID just retrieved.
263
-
264
- Rotation invalidates the old key; perform it only with the user's explicit authorization. Before rotating, identify applications using the key and prepare to update their secrets. If `OPENANY_DEV_API_KEY` still contains the old value, it takes precedence over the newly saved CLI key, so update the environment and verify it as well. If the outcome is unclear, verify the state before deciding what to do next.
265
-
266
- ## Email Login and Key Management
267
-
268
- ```bash
269
- openany-dev auth email send -j
270
- openany-dev auth email verify --code SIX_DIGITS -j
271
- openany-dev auth email workspace --workspace WORKSPACE_ID -j
272
- openany-dev auth email refresh -j
273
- openany-dev keys remote list --limit 100 --offset 0 -j
274
- openany-dev keys remote create --label agent-main -j
275
- openany-dev keys remote get --id KEY_ID -j
276
- openany-dev keys remote revoke --id KEY_ID -j
277
- ```
278
-
279
- **Email sign-in and new-account registration:** Read the configured email address and run `openany-dev auth email send -j` once. This sends the six-digit email code before the registration branch:
280
-
281
- - **New email (`registrationRequired: true`):** Immediately display the exact returned `verificationUrl` as a clickable browser link, including its full `#` fragment. The CLI also prints this link to stderr, including in JSON mode. Tell the user to open it, check the email address, and complete **Turnstile** themselves. Wait for their confirmation before verifying the email code; do not solve the challenge on their behalf. Browser approval alone does not register or log in: the same request must also pass email-code verification.
282
- - **Existing account (no registration requirement):** Continue directly to email-code verification; do not request browser Turnstile.
283
- - After browser approval when required, obtain the current six-digit code through the authorized mailbox flow below and run `openany-dev auth email verify --code SIX_DIGITS -j`. Preserve leading zeros. Only a successful verify response completes registration/login; then select a workspace if required.
284
- - If verify returns `HUMAN_VERIFICATION_REQUIRED`, ask the user to finish the already-issued browser link and retry verification for the same challenge after confirmation. Do not repeatedly send new codes. If the challenge expires, request a fresh code and, for a new email, present its new link; resending invalidates the previous link and code. A missing or invalid required link is an error: do not invent a URL or skip human verification.
285
-
286
- Read the current verification code through an authorized email connection, preserving all six digits and any leading zeros. If the email connection is unavailable, collect the current code using the email-code input form described above; use terminal verification only when forms are unavailable. Do not send another code just because mailbox access is unavailable; only request a fresh challenge after expiry and repeat its required browser verification. Never request the mailbox password. Use the dedicated form for the current login code and do not repeat its value. Avoid sending codes repeatedly. A single workspace is selected automatically; if there are multiple workspaces, select the one authorized by the user. Relevant commands also accept `--workspace ID`.
287
-
288
- The CLI saves email login state but does not automatically refresh it. For an expired email session, explicitly run `openany-dev auth email refresh -j`; if refresh is denied, log in again through the authorized mailbox. If refresh has an uncertain outcome or returns a recovery file, follow the recovery error before retrying. Refreshing an email session does not repair an invalid API key. Remote key lists use `limit/offset` pagination. Updating an email-based key requires separate steps: create a new key → update applications using it → verify the new key → revoke the specified old key within the user's authorization. Keep the old key until verification is complete to avoid disrupting existing calls.
289
-
290
- ## Authorized Top-Ups
291
-
292
- ### Low-Balance Guidance
293
-
294
- Use `availableMicroUsd` from the current API key's balance check. A low balance means less than **5 USD** (5,000,000 microUSD); exactly 5 USD does not trigger a low-balance prompt or automatic top-up.
295
-
296
- - **User-provided API key with no wallet information:** When the balance is below 5 USD, explain that this is a reminder and the remaining balance is still usable for affordable authorized calls. Offer manual recharge in the OpenAny dashboard at **https://dev.openany.si** as optional unless the selected request exceeds the available funds. For example: "Your balance is below the $5 reminder threshold, but you can still use it for calls it covers. You can recharge manually in the OpenAny dashboard when needed." Do not invite automatic top-up authorization or guide wallet binding/setup as a response to this low balance.
297
- - **API key confirmed to have been generated when the user created an account by binding a wallet, without existing automatic top-up authorization:** You may offer the authorization walkthrough below. Creating an account or generating a key does not itself authorize payments.
298
- - **Other or unknown key origins without existing authorization:** Do not invite automatic top-up authorization. If a recharge is needed, direct the user to the OpenAny dashboard. A configured payment wallet alone does not prove that the current API key was generated through wallet-based account creation; do not infer its origin.
299
- - **Existing automatic top-up authorization:** Reuse valid approval for the current account and task under **Execute Authorized Top-Ups**; do not ask for the same approval again. Authorization does not replace required wallet information or payment checks.
300
-
301
- A low-balance warning alone does not prevent calls that the remaining balance can cover within the user's task and budget.
302
-
303
- ### Explain How to Enable Top-Ups
304
-
305
- Offer this authorization walkthrough only when the current API key is confirmed to have been generated through wallet-based account creation and the user has not authorized automatic top-ups. A low balance or a question about automatic top-ups does not establish that eligibility; otherwise follow **Low-Balance Guidance**. Give eligible users an actionable walkthrough in their language. Do not end with only "provide authorization, limits, network, scope, and expiration" or a `topups authorize` command. Keep the completed connection checks unchanged and explain the following next steps:
306
-
307
- 1. **Choose whether to enable it.** Explain that top-ups are optional: the user can reply "Not now" and use the remaining balance while it covers the requested calls. Enabling means that when the agent checks the balance and finds less than 5 USD, it attempts a top-up with a 10 USD input amount within the approved limits. Fees can change the actual payment or net credit. There is no background monitor, and a currently low balance can trigger a top-up as soon as authorization and setup are complete.
308
- 2. **Identify the account and payment wallet.** Reuse the confirmed wallet account information and ask only for any missing payment wallet/network choice. Explain that the network is the blockchain holding the wallet's payment funds, not Wi-Fi or a bank card network. If the user does not know, offer the exact reply "Guide me through setup; I don't know my wallet network." This requests help, not payment permission. Resolve those choices before presenting a ready-to-approve plan; do not choose a network from an address format alone. Use the wallet identity's network support below. If no wallet information is available, direct the user to manual recharge instead of starting wallet setup from a low-balance warning.
309
- 3. **Provide a copyable approval message.** Fill only facts already known, explain any remaining fields, and let the user edit them. A single-payment limit caps each actual payment including fees; the total limit caps all payments under this authorization, not the account's monthly API spending limit. Purpose means the specific task whose balance checks may trigger top-ups. Expiration needs a date, time, and time zone. Do not invent approved values or treat an unfilled template, example, silence, or a request for help as consent:
310
-
311
- > I authorize low-balance top-ups for [account to credit], paid from [payment wallet address] on [network]. When you check the balance during [specific task] and it is below 5 USD, use a 10 USD top-up input amount. Each actual payment including fees must not exceed [single-payment limit] USD, and all payments under this authorization must not exceed [total limit] USD. This authorization expires at [date, time, time zone]. If the quote exceeds either limit, stop and ask me. Within these limits, you may complete the required login, record the authorization, and execute top-ups without asking again.
312
-
313
- 4. **Guide only missing local setup.** After the eligible user chooses to enable top-ups, guide any missing local signing configuration for the known wallet. Tell the user to open their own terminal on the machine/account running OpenAny, run `openany-dev setup --scenario wallet`, and explain the hidden private-key prompt, automatic address display, and stable Agent ID input (for example `openany-main`, retained for later use). Apply the full sensitive-information warning and local-storage guidance from **Missing Configuration: Required User Guidance**. Existing authorized signing tools follow the external-signing flow instead. Ask the user to reply only "Configured" when done; setup completion alone is not payment approval.
314
- 5. **Explain what the agent does next.** After explicit approval, check local configuration, complete wallet login, verify the account to credit, record the approved policy with `topups authorize`, and rerun payment preflight with wallet identity and the approved scope. Translate a confirmed network name to its CLI identifier and the approved expiration to an ISO timestamp; clarify any ambiguity. The user does not need to construct CLI flags. Report readiness only after the checks pass; report payment and credit only after their respective confirmations.
315
-
316
- Keep the first response manageable: show the approval template and the next applicable action. If the wallet network is unknown, ask for that information first and explain that local configuration follows. A reply such as "Enable it" with missing limits is a request to finish this walkthrough, not unrestricted payment permission. When all required details were already explicitly approved, continue within that approval without asking the user to approve them again.
317
-
318
- ### Execute Authorized Top-Ups
319
-
320
- Use only when the user has explicitly authorized autonomous top-ups. Before creating or paying for an order, complete login and policy setup within that authorization. For wallet identity, complete Wallet Login and API Key Management above before creating an order (first-time wallet: create key → login; existing wallet key: login directly); for email identity, log in and select a workspace first. The API key must belong to the top-up target. Wallet identity supports the EVM networks published by the service; email identity supports Base `eip155:8453` and Solana `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`.
321
-
322
- A payment preflight requires a login session and a saved payment policy. If it reports `wallet_session` or `email_session` missing, follow the corresponding authorized login flow above. If `payment_policy` is missing, record the user's existing approval with `topups authorize`; ask only when credentials, tools, or approval details are missing. Then rerun the payment check with the target identity and task scope, as shown below. Do not manually edit the credentials file to supply sessions or policies.
323
-
324
- Whenever the agent checks the available balance (`availableMicroUsd`) and finds less than **5 USD** (5,000,000 microUSD), initiate a top-up with `--amount-usd 10` if autonomous top-ups are authorized, without asking for confirmation again within that authorization. A balance of exactly 5 USD does not trigger a top-up. The 10 USD is the command input amount, not a guarantee of 10 USD net credit or a target balance. Respect the approved network, actual payment limits (including fees), scope, and expiration; if they do not permit the purchase, ask the user to update the authorization. Resolve any pending or uncertain top-up using its existing intent before creating another, and recheck the balance after confirmed crediting. This is an agent-executed policy; the CLI does not monitor balances or run a background auto-top-up loop.
325
-
326
- First record the network, limits, purpose, and expiration already approved by the user, then create and pay for the order. Changing limits or extending the expiration requires additional user authorization:
327
-
328
- ```bash
329
- openany-dev topups authorize --identity wallet --network eip155:8453 --max-single-usd USER_APPROVED_SINGLE_LIMIT --max-total-usd USER_APPROVED_TOTAL_LIMIT --scope TASK_SCOPE --expires-at USER_APPROVED_ISO_TIME -j
330
- openany-dev status --scenario payment --identity wallet --scope TASK_SCOPE -j
331
- openany-dev topups create --scope TASK_SCOPE --intent UNIQUE_INTENT --amount-usd 10 --network eip155:8453 -j
332
- openany-dev topups pay --intent UNIQUE_INTENT -j
333
- openany-dev topups get --intent UNIQUE_INTENT -j
334
- ```
335
-
336
- Read the locked quote before signing: `inputAmountMeaning` defines the input amount, `payAmountMicroUsd` is the actual payment, `feeAmountMicroUsd` is the fee, and `creditAmountMicroUsd` is the balance credit. With `add_on`, a 10 USD input credits 10 USD and adds the fee to payment. With `deduct_from_credit`, a 10 USD input pays 10 USD and credits less after the fee. Preserve `--amount-usd 10` for this policy; do not silently increase it to force a net credit of 10 USD. Report the actual quoted and credited amounts.
337
-
338
- Amounts are in USD with up to six decimal places. The 10 USD input above is the authorized low-balance policy amount; authorization limits and other placeholders must use values already approved by the user. Limit checks include fees, and pending orders also reserve part of the total allowance. `authorize` records existing authorization locally; running this command does not itself mean the user has approved a top-up.
339
-
340
- - Choose and retain the top-up identifier (intent) before creating an order, and retain the returned order ID. The CLI generates and persists the idempotency key before sending the request and reuses it for the same intent; do not read the credentials file to extract it. Always use the same intent, scope, amount, and network for the same top-up. If creation has an unclear outcome, wait for the current request to finish, then resume with the original parameters plus `--resume` to avoid creating duplicate orders.
341
- - `pay` validates the order's locked quote, resource domain, recipient, network, amount, payment wallet, expiration, and authorized budget. EVM uses EIP-3009 signing; for Solana, the CLI validates and signs the transaction returned by the service, which then submits it.
342
- - External signing: `create --prepare` does not require a private key; `pay --prepare` returns the payload to sign. After signing, submit it with `pay --intent NAME --signature-file FILE`. The payment signature file format is `{"signature":"EVM_SIGNATURE"}` or `{"transaction":"BASE64_SIGNED_SOLANA_TRANSACTION"}`. If the signing payload expires, run `pay --prepare` again for the original order.
343
- - After payment has been submitted, timed out, or has an unknown outcome, check status only with `topups get --intent NAME`. Do not pay again, change the idempotency key, or bypass the CLI. Report the funds as credited only after confirming `paymentStatus=paid` and `creditStatus=credited`; wallet identity also requires `accountUsable=true`.
344
- - For email identity, use `topups config` and `topups quote --amount-usd AMOUNT --network CAIP2` to view top-up configuration and estimates first; the order's locked quote governs the actual payment.
345
- - If service domains do not match, pause and ask the user to contact OpenAny support. Do not switch service domains or modify the message to sign.
346
-
347
- ## Errors and Recovery
348
-
349
- On failure, the CLI returns a nonzero exit code and writes `{"error":{"code":"...","message":"..."}}` to standard error (stderr), possibly including `requestId`, `status`, and `missing`. Explain the error to the user and retain the error code and request ID without exposing credentials. Judge success by the final business outcome; HTTP 200, heartbeats, or the start of a stream indicate only request progress.
350
-
351
- If login or key management succeeds on the server but cannot be saved locally, the CLI returns the path to a recovery file with restricted access. Use `openany-dev auth recover --file RETURNED_PATH` to recover the original result and avoid creating duplicate keys; import only verified recovery files. For other unclear outcomes, follow the error guidance. If the configuration lock is held, first check whether the associated process is still running. If the process has exited but the lock remains, ask a maintainer to help clear the specified lock; do not automatically delete locks or retry payments.
352
-
353
- A balance query verifies only the current key's ability to access the balance. It does not verify wallet signing, email connectivity, or payment permissions. If a required capability is missing, explain exactly what is missing and the next configuration steps. Report task completion based on actual execution results.
34
+ Follow [the seller review workflow](./calls.md#seller-reviews) in the environment of the verified call.