CoinFello CLI Skill

Use the npx @coinfello/agent-cli@latest CLI to interact with CoinFello. The CLI handles smart account creation, SIWE authentication, delegation management, prompt-based transactions, and transaction status checks.

Prerequisites

• Node.js 20 or later (npx is included with Node.js)

Environment Variables

Security Notice

This skill performs the following sensitive operations:

• Key generation and storage: By default, create_account generates a hardware-backed P256 key in the macOS Secure Enclave (or TPM 2.0 where available). The private key never leaves the hardware and cannot be exported — only public key coordinates and a key tag are saved to ~/.clawdbot/skills/coinfello/config.json. If hardware key support is not available, the CLI warns and falls back to a software private key. You can also explicitly opt into a plaintext software key by passing --use-unsafe-private-key, which stores a raw private key in the config file — this is intended only for development and testing.
• Signer daemon: Running signer-daemon start authenticates once via Touch ID / password and caches the authorization. All subsequent signing operations reuse this cached context, eliminating repeated auth prompts. The daemon communicates over a user-scoped Unix domain socket with restricted permissions (0600). If the daemon is not running, signing operations fall back to direct execution (prompting Touch ID each time).
• Session token storage: Running sign_in stores a SIWE session token in the same config file.
• Delegation signing: Running send_prompt may automatically create and sign blockchain delegations based on server-requested scopes, then submit them to the CoinFello API.

Quick Start

# 1. Start the signing daemon (optional, but avoids repeated Touch ID prompts)
npx @coinfello/agent-cli@latest signer-daemon start

# 2. Create a smart account (uses Secure Enclave by default)
npx @coinfello/agent-cli@latest create_account

# 3. Sign in to CoinFello with your smart account (SIWE)
npx @coinfello/agent-cli@latest sign_in

# 4. Send a natural language prompt — the server will request a delegation if needed
npx @coinfello/agent-cli@latest send_prompt "send 5 USDC to 0xRecipient..."

Commands

create_account

Creates a MetaMask Hybrid smart account. By default, the signing key is generated in the macOS Secure Enclave (hardware-backed, non-exportable). If Secure Enclave is unavailable, the CLI warns and falls back to a software key. Pass --use-unsafe-private-key to explicitly use a plaintext software key (development/testing only).

npx @coinfello/agent-cli@latest create_account [--use-unsafe-private-key]

• Default (Secure Enclave): Generates a P256 key in hardware; saves key_tag, public_key_x, public_key_y, key_id, and smart_account_address to ~/.clawdbot/skills/coinfello/config.json. The private key never leaves the Secure Enclave.
• --use-unsafe-private-key: Generates a random secp256k1 private key and stores it in plaintext in the config file. Use only for development and testing.
• Must be run before send_prompt

get_account

Displays the current smart account address from local config.

npx @coinfello/agent-cli@latest get_account

• Prints the stored smart_account_address
• Exits with an error if no account has been created yet

sign_in

Authenticates with CoinFello using Sign-In with Ethereum (SIWE) and your smart account. Saves the session token to local config.

npx @coinfello/agent-cli@latest sign_in

• Signs in using the private key stored in config
• Saves the session token to ~/.clawdbot/skills/coinfello/config.json
• The session token is loaded automatically for subsequent send_prompt calls
• Must be run after create_account and before send_prompt for authenticated flows

set_delegation

Stores a signed parent delegation (JSON) in local config.

npx @coinfello/agent-cli@latest set_delegation '<delegation-json>'

• — A JSON string representing a Delegation object from MetaMask Smart Accounts Kit

new_chat

Clears the saved chat session ID from local config so the next send_prompt starts a fresh conversation.

npx @coinfello/agent-cli@latest new_chat

• Removes chat_id from ~/.clawdbot/skills/coinfello/config.json
• Use this when you want to reset conversation context (for example, after context-window errors)

signer-daemon

Manages the Secure Enclave signing daemon. Starting the daemon authenticates once via Touch ID / password and caches the authorization, so subsequent signing operations (account creation, sign-in, delegation signing) do not prompt again.

npx @coinfello/agent-cli@latest signer-daemon start    # Start daemon (one-time auth)
npx @coinfello/agent-cli@latest signer-daemon status   # Check if daemon is running
npx @coinfello/agent-cli@latest signer-daemon stop     # Stop the daemon

• If the daemon is not running, all Secure Enclave operations fall back to direct execution (prompting Touch ID each time)
• The daemon is optional — all commands work without it

send_prompt

Sends a natural language prompt to CoinFello. If the server requires a delegation to execute the action, the CLI creates and signs a subdelegation automatically based on the server's requested scope and chain.

npx @coinfello/agent-cli@latest send_prompt "<prompt>"

Note that if you receive Failed to send prompt: Conversation request failed (400): {"error":"Your input exceeds the context window of this model. Please adjust your input or start a new chat and try again."} then you should call npx @coinfello/agent-cli@latest new_chat to start a new chat with a new context window.

What happens internally:

• Fetches available agents from /api/v1/automation/coinfello-agents and sends the prompt to CoinFello's conversation endpoint
• If the server returns a read-only response (no clientToolCalls and no txn_id) → prints the response text and exits
• If the server returns a txn_id directly with no tool calls → prints it and exits
• If the server sends an ask_for_delegation client tool call with a chainId and scope:
• Fetches CoinFello's delegate address
• Rebuilds the smart account using the chain ID from the tool call
• Parses the server-provided scope (supports ERC-20, native token, ERC-721, and function call scopes)
• Creates and signs a subdelegation (wraps with ERC-6492 signature if the smart account is not yet deployed on-chain)
• Sends the signed delegation back as a clientToolCallResponse along with the chatId and callId from the initial response
• Returns a txn_id for tracking

Common Workflows

Basic: Send a Prompt (Server-Driven Delegation)

# Start the signing daemon (optional, reduces Touch ID prompts)
npx @coinfello/agent-cli@latest signer-daemon start

# Create account if not already done (uses Secure Enclave by default)
npx @coinfello/agent-cli@latest create_account

# Sign in (required for delegation flows)
npx @coinfello/agent-cli@latest sign_in

# Send a natural language prompt — delegation is handled automatically
npx @coinfello/agent-cli@latest send_prompt "send 5 USDC to 0xRecipient..."

Read-Only Prompt

Some prompts don't require a transaction. The CLI detects this automatically and just prints the response.

npx @coinfello/agent-cli@latest send_prompt "what is the chain ID for Base?"

Gas Cost Estimates

Actual on-chain gas costs vary by network. Do not assume mainnet Ethereum gas prices for L2 chains.

Edge Cases

• No smart account: Run create_account before send_prompt. The CLI checks for a saved private key and address in config.
• Not signed in: Run sign_in before send_prompt if the server requires authentication.
• Invalid chain name: The CLI throws an error listing valid viem chain names.
• Read-only response: If the server returns a text response with no transaction, the CLI prints it and exits without creating a delegation.

Reference

See references/REFERENCE.md for the full config schema, supported chains, API details, scope types, and troubleshooting.