feat: let a one-line agent prompt set up Zerion via init + the skill

[evgeth]

Why

For an agent to do on-chain work with the Zerion CLI today, the prompt has to spell out a lot: how to install and log in, which version is needed, how to register a read-only wallet, and the rules for building and signing transactions safely. That makes prompts long, hard to read, and out of date as soon as the CLI changes.

This PR moves that knowledge into zerion init and the zerion skill, so a prompt can be just the request plus one fixed line:

Using the Zerion CLI, exit all my positions and sell all my tokens on Blast, then move everything to Ethereum.

Wallet: 0xYourWallet
Start by running `npx -y zerion-cli@latest init -y`.

The agent runs init, which installs or upgrades the CLI and the skill, then reads SKILL.md and works out which capability docs the request needs. Nothing here is exit-specific, and it should behave the same in Claude Code, Codex, Cursor and Gemini CLI.

What changed

zerion init (cli/commands/init.js)

• Actually installs globally (bug fix). Under npx, the temp copy is first on PATH, so zerion --version always succeeded. init reported "already installed" and never ran npm install -g, even on a fresh machine. Run from a project's node_modules, it made the same false claim, because it only looked for _npx in the path. It now finds the global copy via `npm root -g`/zerion-cli and compares real paths: if this process is the global copy (including an npm linked checkout) it skips, otherwise it installs or upgrades.
• Upgrades old global installs. A global copy older than the running one is upgraded to that exact version instead of being kept.
• Detects Codex correctly. It now uses CODEX_SANDBOX / CODEX_CI / CODEX_THREAD_ID, the markers @vercel/detect-agent uses and that npx skills relies on, instead of CODEX_HOME. CODEX_HOME still relocates ~/.codex.
• Fixes the Gemini id (bug fix). The id is now gemini-cli. skills add -a gemini was rejected as an invalid agent.
• Installs the skill for every agent on the machine, with the running agent first. Before, it picked the first of ~/.claude, ~/.cursor, ~/.codex, so a prompt pasted into Codex on a machine that also had Claude Code installed the skill into Claude Code only.
• Still never blocks without a TTY. This is deliberate. Waiting up to 5 minutes for browser login could hit the agent's command timeout (Claude Code's default is 2 minutes), and because auth runs before the skills step, a killed init would leave no skill installed. Instead:
  • Inside an agent, init prints zerion login --browser with instructions to run it in the background and show the user the URL.
  • The auth step's JSON gets "next": "zerion login --browser".
  • The key fallback hint now says zerion login --browser too, because plain zerion login exits with not_interactive when there's no TTY.
• Points the agent at SKILL.md. init prints the path of the skill shipped in the package and adds skill to the JSON. Agents load skills at session start, so a skill installed mid-session may not be visible yet.

Skill

• SKILL.md:
  • A setup check that probes first and skips finished steps: version, login, registering a read-only wallet, and a note on sandboxed agents.
  • "Rules for every on-chain task": exact on-chain balances, gas vs. proceeds (stop and ask when gas wins), swaps/bridges/transfers only through swap/bridge/send (never hand-encoded), signing-link handling, scope discipline.
  • Routing for requests that combine several capabilities.
  • Fixes the claim that every trade needs an agent token. Read-only wallets sign in the web app and need none.
• New capabilities/defi-exit.md: find positions, pick the way out (including selling the receipt token vs. waiting out a cooldown), research the contract (ABIs from Sourcify, plus viem from the CLI install), build the protocol step, and the "after the exit" review that stops and waits.
• capabilities/bundle.md:
  • A "Hand-built groups" section for withdraw/claim steps, with the envelope field rules. I checked them against parsePreparedGroup and decideBundleRoute; route alone decides the signing path.
  • bundle ignores --wallet and takes the signer from each envelope. The docs now say so instead of telling agents to pass it.

--quote on swap and bridge

Prints the price and stops, skipping the balance check. An exit's gas-vs-proceeds check has to price tokens that a claim or unstake hasn't delivered yet, and --prepare rejects those with insufficient_funds. In an agent test run, the agent worked around this by importing CLI internals and quoting with another holder's address.

• With a short balance, the result is marked enoughBalance: false with a note that the price is indicative, since the API leaves out network gas and the protocol fee until the tokens are there.
• --quote and --prepare are rejected together (conflicting_flags).
• The insufficient_funds error now suggests --quote.
• bridge … --quote lists every route and its price, then stops. Plain bridge lists routes only when there are several, executes a single one, and refuses a short balance. --quote always lists, never executes, and prices tokens the wallet doesn't hold yet. An agent in a test run tried bridge --quote before it existed and the flag was silently ignored. The route listing and balance check moved into tested helpers; plain bridge behaves as before.
• SKILL.md, trading.md and defi-exit.md use --quote for pricing, and the CLI help lists it for both commands.

Signing links are one-time

SKILL.md now says a link belongs to the run that printed it. Once that run ends, the agent shouldn't re-share it: the CLI no longer receives the result, and because the transaction travels inside the link, signing it and a fresh one could execute the action twice. The agent checks the chain first, then generates a new link if nothing went through. An agent in the same test run had re-shared an expired link.

Chain ids and public RPCs in zerion chains; ABIs from Sourcify

• zerion chains prints each EVM chain's chainId (decimal) and chainIdHex, taken from the external_id the chains API already returns. Agents need the number for ABI lookups and the hex form for a hand-built envelope's chainId. Solana gets none. The table view gains a Chain ID column.
• zerion chains --json also prints each chain's rpcUrls: the public HTTPS endpoints from the chains API's rpc.public_servers_url, in catalog order, without WebSocket URLs. None needs a key. In a keyless test, 134 of the 177 listed HTTPS URLs answered with the right chain ID, covering 55 of 65 EVM chains. The <chain>.drpc.org pattern the docs used before reached 46, all of which the catalog also covers. SKILL.md now says to use $ETH_RPC_URL if set, otherwise try rpcUrls in order, skipping any that errors or answers with a different chain ID, and to say so if none answers.
• defi-exit.md gets ABIs from Sourcify's keyless v2 API by chain ID, following proxyResolution to implementation contracts. Blockscout's <chain>.blockscout.com didn't exist for many chains we tried, and its API started returning Cloudflare challenges after a few requests; Sourcify found all 16 DeFi contracts tested across Ethereum and Base. Etherscan's V2 API is a fallback only when the user already has ETHERSCAN_API_KEY set, since it rejects keyless requests. With no verified ABI, agents stop rather than scrape explorer pages or guess.

Telling users which wallet signs

When sharing a signing link, SKILL.md now has the agent tell the user what to expect. app.zerion.io shows the full review first: signing address, balance changes, fee, and a security check. If no wallet is connected, it then asks them to connect one, and it must be the wallet that owns the signing address. I confirmed the page's behavior in a browser with no wallet connected.

npx zerion-cli@latest init in docs and help

A bare npx zerion-cli runs whatever global copy is installed. With zerion-cli 1.6.0 installed globally, bare npx zerion-cli --version printed 1.6.0, and @latest printed 1.9.1. Because init installs globally, returning users would otherwise never run new code. The README, the router's setup.init help, the init HELP examples and two partner docs now use @latest.

Testing

• Unit tests: all 513 pass on Node 20 (after merging main), including 17 new init tests, 6 for --quote on swap and bridge, and 5 for chain IDs and RPC URLs:
  • agent vs. non-agent login hints
  • the skill path
  • install / upgrade / skip from npx, from a project's node_modules, and from the global copy itself, using a fake npm
  • version comparison (full semver precedence, including next prereleases)
  • agent detection and skill targets
  • Note: npm test's ** pattern needs Node 21+; on 20, list the test files explicitly. CI uses Node 24.
• End to end: ran npm pack, then npx -y file:<tgz> init -y with a temp HOME containing ~/.claude and ~/.codex, CODEX_THREAD_ID set and no API key. Result:
  • exit 0
  • global install correctly skipped (same version)
  • the login hint and next were printed
  • the skill was installed to ~/.agents/skills/zerion ("universal: Codex") and linked into Claude Code
  • the SKILL.md path was printed

Reviewer notes

• Merge this, then release right away. npx skills add installs the skill from main, but the CLI comes from npm. The skill now requires CLI 1.11.0 (the release this lands in) before using --quote. 1.10.0 silently ignores --quote and runs the swap or bridge: with a read-only wallet that produces a signing link, and with an agent token it would execute. Until 1.11.0 is on npm, agents following the new skill stop at the version check, which is safe but blocks them, so merge the release PR soon after this one.

• JSON output change: the skills step's JSON now reports agents: [...] instead of agent.

• Not in this PR: three CLI follow-ups that would remove more rules from the docs:

  • bundle choosing the web-app route on its own for read-only wallets
  • a --no-wait flag that prints the signing link and exits
  • bundle refusing hand-built swap/approve/transfer calls

🤖 Generated with Claude Code