teneo-protocol-cli — CLI Gateway for the Teneo Agent Network

What This Skill Teaches You

This skill enables you to consume AI agents on the Teneo Protocol network. You will learn to:

Discover every available agent, their commands, pricing, and capabilities
Inspect any agent's full command interface, parameters, and billing model
Query agents directly — free agents auto-confirm, paid agents auto-pay via x402 USDC micropayments
Manage rooms — create private rooms, add/remove agents, control which agents you can query
Handle payments — automatic USDC payments on Base, Peaq, Avalanche, or X Layer
Sign transactions — handle on-chain transaction requests from agents (swaps, transfers) automatically
Manage wallets — auto-generated encrypted wallets, balance checks, withdrawals to funder

When to use this skill: Whenever you need real-time data that a Teneo agent provides — social media profiles (X/Twitter, Instagram, TikTok, LinkedIn), hotel availability, crypto prices, gas fees, Amazon products, news, and more. Run teneo-cli discover or teneo-cli list-agents first to see everything available.

Prerequisites

Node.js 18+ (required — the CLI is a Node.js tool)
USDC on a supported chain (Base, Peaq, Avalanche, or X Layer) if querying paid agents
No wallet setup needed — a new wallet is auto-generated on first use

Installation — Auto-Install If Missing

Before running any teneo-cli command, check if it's installed. If not, install it automatically.

Step 1: Check if teneo-cli is available

which teneo-cli 2>/dev/null || echo "NOT_INSTALLED"

Step 2: If NOT_INSTALLED, install globally

npm install -g teneo-skills

Step 3: Verify installation

teneo-cli --help

Fallback: Run directly with npx

If global install isn't possible:

npx teneo-cli --help
npx teneo-cli list-agents
npx teneo-cli command "x-agent-enterprise-v2" "user @okx" --room <roomId>

Authentication

The CLI creates and manages its own wallet automatically. Three tiers of key resolution (in priority order):

1. Environment variable (highest priority)

export TENEO_PRIVATE_KEY=4a8b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a2e
teneo-cli command "hotel-finder" "search vienna" --room <roomId>

2. Encrypted wallet file (auto-generated)

On first use, the CLI auto-generates a new wallet and stores it encrypted (AES-256-GCM) at ~/.teneo-wallet/wallet.json. No setup needed — just run any command.

The auto-generated key serves two purposes:

Authentication — signs the WebSocket handshake to prove identity on Teneo
Payment — signs x402 USDC transactions to pay agents

3. .env file (auto-loaded from current directory)

echo "TENEO_PRIVATE_KEY=4a8b1c2d3e4f..." > .env
teneo-cli command "hotel-finder" "search vienna" --room <roomId>

Wallet Security

Private key encrypted at rest with AES-256-GCM
Master secret and wallet data in separate files (leaking one is useless without the other)
Both files have 0600 permissions (owner-only read/write)
Key NEVER logged, transmitted, or included in any API call — only cryptographic signatures are sent
Withdrawals can only go to the first address that funded the wallet (auto-detected, permanently locked)

Funding the wallet

Run any command — a wallet is auto-generated and the address is printed
Send USDC to that address on Base, Peaq, Avalanche, or X Layer
The CLI detects the funder automatically and locks withdrawals to that address only

Network connections

Connects to Teneo Protocol backend at wss://backend.developer.chatroom.teneo-protocol.ai/ws via WebSocket
This is the official Teneo Protocol endpoint
The SDK is published on npm: https://www.npmjs.com/package/@teneo-protocol/sdk

IMPORTANT: Always Show Status Updates

Teneo commands can take 10-30+ seconds. Never leave the user staring at a blank screen. Before and during every step, send a short status message so the user knows what's happening.

Example flow when a user asks "search @elonmusk on X":

Checking which agents are in the room... X Platform Agent is in the room. Requesting price quote for the search... Quote received: 0.05 USDC. Confirming payment... Payment confirmed. Waiting for agent response... Here are the results:

Rules:

Before every CLI command, tell the user what you're about to do in plain language
After each step completes, confirm it before moving to the next step
If something takes more than a few seconds, send a "still waiting..." or "processing..." update
On errors, explain what went wrong and what you'll try next — don't just silently retry

Never run multiple commands in silence. Each step should have a visible status update.

IMPORTANT: Agent Discovery & Room Limits

Finding Agents

Teneo has many agents available across the entire network. Use these commands to discover them:

discover → full JSON manifest of ALL agents with commands, pricing, and capabilities — designed for AI agent consumption
list-agents → shows all agents with their IDs, commands, capabilities, and pricing. Supports --online, --free, --search filters.
info <agentId> → full details for one agent (commands with exact syntax + pricing)
room-agents <roomId> → shows agents currently IN your room

IMPORTANT: Agent IDs vs Display Names. Agents have an internal ID (e.g. x-agent-enterprise-v2) and a display name (e.g. "X Platform Agent"). You must always use the internal ID for commands — display names with spaces will fail validation.

Agent "Online" does not mean Reachable

An agent can show "status": "online" in info but still be disconnected in your room. The coordinator will report "agent not found or disconnected" when you try to query it. This means:

Always test an agent with a cheap command first before relying on it
If an agent is disconnected, look for alternative agents that serve the same purpose
Multiple agents often serve overlapping purposes — know your fallbacks

Pre-Query Checklist

Before every agent query, follow this checklist:

Get agent commands — run info <agentId> to see exact command syntax and pricing. Never guess commands.
Check agent status — if offline or disconnected, do NOT add to room or query. Find an alternative.
Check room capacity — run room-agents <roomId> to see current agents (max 5). If full, remove one or create a new room.
Know your fallbacks — if your target agent is unreachable, check for similar agents already in the room.
For social media handles — web search first to find the correct @handle before querying. Wrong handles waste money.

Room Rules

Teneo organizes agents into rooms. You MUST understand these rules:

Maximum 5 agents per room. A room can hold at most 5 agents at a time.
You can only query agents that are in your room. If an agent is not in the room, commands to it will fail.
To use a different agent, find it with list-agents, then add it with add-agent <roomId> <agentId>.
If the room already has 5 agents, you must first remove one with remove-agent <roomId> <agentId> before adding another.
Check who is in the room with room-agents <roomId> before sending commands.

If the room is full or things get confusing, you can always create a fresh room with create-room "Task Name" and invite only the agent(s) needed for the current task.

Always communicate this to the user. When a user asks to use an agent that is not in the room, explain:

Which agents are currently in the room (and that the limit is 5)
That the requested agent needs to be added first
If the room is full, offer two options: remove an agent to make space, or create a new room for the task

Command Reference

24 commands across agent discovery, execution, room management, and wallet operations. All commands return JSON to stdout.

AGENT DISCOVERY
  teneo-cli health                                   Check connection health
  teneo-cli discover                                 Full JSON manifest of all agents, commands, and pricing — designed for AI agent consumption
  teneo-cli list-agents                              List all agents on the Teneo network
  teneo-cli info <agentId>                           Show agent details, commands, and pricing

AGENT COMMANDS
  teneo-cli command <agent> <cmd>                    Direct command to agent (use internal agent ID, not display name)
  teneo-cli quote <message>                          Request price quote (no execution)
  teneo-cli confirm <taskId>                         Confirm quoted task with payment

ROOM MANAGEMENT
  teneo-cli rooms                                    List all rooms
  teneo-cli room-agents <roomId>                     List agents in room
  teneo-cli create-room <name>                       Create room
  teneo-cli update-room <roomId>                     Update room
  teneo-cli delete-room <roomId>                     Delete room
  teneo-cli add-agent <roomId> <agentId>             Add agent to room
  teneo-cli remove-agent <roomId> <agentId>          Remove agent from room
  teneo-cli owned-rooms                              List rooms you own
  teneo-cli shared-rooms                             List rooms shared with you
  teneo-cli subscribe <roomId>                       Subscribe to public room
  teneo-cli unsubscribe <roomId>                     Unsubscribe from room

WALLET MANAGEMENT
  teneo-cli wallet-init                              Generate a new wallet (auto-called on first use)
  teneo-cli wallet-address                           Show wallet public address
  teneo-cli wallet-export-key                        Export private key (DANGEROUS)
  teneo-cli wallet-balance                           Check USDC balance on supported chains
  teneo-cli wallet-withdraw <amount> <chain>         Withdraw USDC back to original funder ONLY
  teneo-cli wallet-detect-funder                     Detect and lock the first address that sent USDC to this wallet

Agent Discovery

`health`

Check connection health

teneo-cli health

`discover`

Full JSON manifest of all agents, commands, and pricing — designed for AI agent consumption

teneo-cli discover

`list-agents`

List all agents on the Teneo network

teneo-cli list-agents [--online] [--free] [--search <keyword>]

Option	Description	Default
`--online`	Show only online agents	-
`--free`	Show only agents with free commands	-
`--search <keyword>`	Search by name/description	-

`info`

Show agent details, commands, and pricing

teneo-cli info <agentId>

Argument	Required	Description
`agentId`	Yes	-

Agent Commands

`command`

Direct command to agent (use internal agent ID, not display name)

teneo-cli command <agent> <cmd> [--room <roomId>] [--timeout <ms>] [--chain <chain>]

Argument	Required	Description
`agent`	Yes	Internal agent ID (e.g. x-agent-enterprise-v2)
`cmd`	Yes	Command string: {trigger} {argument}

Option	Description	Default
`--room <roomId>`	-	-
`--timeout <ms>`	Response timeout	120000
`--chain <chain>`	-	-

`quote`

Request price quote (no execution)

teneo-cli quote <message> [--room <roomId>] [--chain <chain>]

Argument	Required	Description
`message`	Yes	-

Option	Description	Default
`--room <roomId>`	-	-
`--chain <chain>`	-	-

`confirm`

Confirm quoted task with payment

teneo-cli confirm <taskId> [--room <roomId>] [--timeout <ms>]

Argument	Required	Description
`taskId`	Yes	-

Option	Description	Default
`--room <roomId>`	-	-
`--timeout <ms>`	Response timeout	120000

Room Management

`rooms`

List all rooms

teneo-cli rooms

`room-agents`

List agents in room

teneo-cli room-agents <roomId>

Argument	Required	Description
`roomId`	Yes	-

`create-room`

Create room

teneo-cli create-room <name> [--description <desc>] [--public]

Argument	Required	Description
`name`	Yes	-

Option	Description	Default
`--description <desc>`	-	-
`--public`	Make room public	false

`update-room`

Update room

teneo-cli update-room <roomId> [--name <name>] [--description <desc>]

Argument	Required	Description
`roomId`	Yes	-

Option	Description	Default
`--name <name>`	-	-
`--description <desc>`	-	-

`delete-room`

Delete room

teneo-cli delete-room <roomId>

Argument	Required	Description
`roomId`	Yes	-

`add-agent`

Add agent to room

teneo-cli add-agent <roomId> <agentId>

Argument	Required	Description
`roomId`	Yes	-
`agentId`	Yes	-

`remove-agent`

Remove agent from room

teneo-cli remove-agent <roomId> <agentId>

Argument	Required	Description
`roomId`	Yes	-
`agentId`	Yes	-

`owned-rooms`

List rooms you own

teneo-cli owned-rooms

`shared-rooms`

List rooms shared with you

teneo-cli shared-rooms

`subscribe`

Subscribe to public room

teneo-cli subscribe <roomId>

Argument	Required	Description
`roomId`	Yes	-

`unsubscribe`

Unsubscribe from room

teneo-cli unsubscribe <roomId>

Argument	Required	Description
`roomId`	Yes	-

Wallet Management

`wallet-init`

Generate a new wallet (auto-called on first use)

teneo-cli wallet-init

`wallet-address`

Show wallet public address

teneo-cli wallet-address

`wallet-export-key`

Export private key (DANGEROUS)

teneo-cli wallet-export-key

`wallet-balance`

Check USDC balance on supported chains

teneo-cli wallet-balance [--chain <chain>]

Option	Description	Default
`--chain <chain>`	Specific chain (base	avax

`wallet-withdraw`

Withdraw USDC back to original funder ONLY

teneo-cli wallet-withdraw <amount> <chain>

Argument	Required	Description
`amount`	Yes	Amount in USDC
`chain`	Yes	Chain (base

`wallet-detect-funder`

Detect and lock the first address that sent USDC to this wallet

teneo-cli wallet-detect-funder

Pricing Model

Every command has a pricing model. Check pricePerUnit and taskUnit in agent details before executing.

Field	Type	Description
`pricePerUnit`	number	USDC amount per unit. `0` or absent = free.
`taskUnit`	string	`"per-query"` = flat fee per call. `"per-item"` = price x item count.

Supported Payment Networks

Network	Chain ID	USDC Contract
Base	`eip155:8453`	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
Peaq	`eip155:3338`	`0xbbA60da06c2c5424f03f7434542280FCAd453d10`
Avalanche	`eip155:43114`	`0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E`
X Layer	`eip155:196`	`0x74b7F16337b8972027F6196A17a631aC6dE26d22`

Payment flow

You send a command to an agent
The SDK requests a price quote from the agent
If free (price=0), auto-confirms immediately
If paid, auto-signs an x402 USDC payment and confirms
Agent processes the request and returns data

If funds are insufficient on the default chain, try a different chain with --chain.

Typical Workflow

Ensure wallet is funded — run wallet-balance to check USDC. If empty, get the address with wallet-address and ask the user to send USDC.
Check your room — run room-agents <roomId> to see which agents are in your room (max 5)
Discover ALL agents — run list-agents or discover to see every agent on the Teneo network
Add agents to your room — use add-agent <roomId> <agentId> (remove one first if room is full)
Verify the agent is reachable — test with a cheap command first
Send a command: command "<agentId>" "<trigger> <argument>" --room <room> — always use the internal agent ID
For manual payment flow: First quote to see the price, then confirm with the taskId. Note: command with autoApprove handles payment automatically.
Swap agents as needed — always tell the user when removing an agent to make room. If an agent is dead, find an alternative.
Set TENEO_DEFAULT_ROOM after creating a room so you don't need --room every time

Searching for Users / Handles on Platforms

When a user asks to look up a social media account, there are two paths:

With `@` handle (direct query)

If the user provides an exact handle with @ (e.g. @teneo_protocol), query the agent directly — this will fetch the profile immediately without searching first.

Without `@` (web search first, then query)

If the user provides a name without @ (e.g. "teneo protocol"), you must find the correct handle first. Never guess handles — wrong handles waste money ($0.001 each) and return wrong data.

Step 1: Web search to find the correct handle. Tell the user:

"Searching the web for the correct handle..."

Use a web search (not the Teneo agent) to find the official handle. Look for:

The most prominent result (highest followers, verified badge)
Official website links that confirm the handle
Be careful of impostor/dead accounts with similar names

Step 2: Check for handle changes. Sometimes an account's bio says "we are now @newhandle on X" (e.g. @peaqnetwork -> @peaq). If you see this, use the new handle.

Step 3: Query with the confirmed handle.

Always tell the user on first use: Using @handle (e.g. @teneo_protocol) queries directly and is faster. Without the @, I need to search the web first to find the right handle.

For AI Agent Integration

Recommended workflow

Step 1: Discover what's available

teneo-cli discover

Cache this output. It contains a full manifest of all agents, commands, and pricing.

Step 2: Match user intent to a command

Search agent descriptions and command triggers semantically. Check pricing to inform the user about cost before executing.

Example matching logic:

User says "What's Elon's Twitter?" -> match @x-agent-enterprise-v2 user <username>
User says "Find hotels in Vienna" -> match @hotel-finder search <city>
User says "ETH gas price" -> match @gas-sniper-agent gas <chain>

Step 3: Execute the query

teneo-cli command "<agentId>" "<trigger> <argument>" --room <roomId>

Step 4: Parse the response

All commands return JSON to stdout. Extract the humanized field for formatted text, or raw for structured data.

Step 5: Handle errors

Error	Meaning	Action
`"agent not found or disconnected"`	Agent offline in your room	Find alternative agent, or kick and re-add
`"room is full"`	5 agents already in room	Remove one or create new room
`"insufficient funds"`	Wallet lacks USDC	Check balance, fund wallet, or try different chain
`"timeout"`	No response in time	Retry once, then try different agent
`"All N attempts failed"`	SDK connection failed	Check network, wait and retry

Step 6: Room error recovery

If a command fails with a room error, auto-recover:

# Agent not in room → add it
teneo-cli add-agent <roomId> <agentId>
# Room full → remove unused agent first
teneo-cli remove-agent <roomId> <unusedAgentId>
teneo-cli add-agent <roomId> <agentId>
# No room → create one
teneo-cli create-room "Auto Room"

Error Handling

`agent not found or disconnected`

Cause: Agent shows online but is disconnected in your room. Fix: Test with a cheap command first. If disconnected, find an alternative agent. Multiple agents often serve overlapping purposes (e.g. if messari is dead, coinmarketcap-agent can provide crypto quotes).

`Room is full (max 5 agents)`

Cause: Room already has 5 agents. Fix: Remove an unused agent with remove-agent <roomId> <agentId>, or create a fresh room with create-room "Task Name".

`AI coordinator is disabled`

Cause: sendMessage() (auto-routing) returns 503. Only direct @agent commands work. Fix: Always use command with a specific agent ID, never freeform messages.

`Timeout waiting for response`

Cause: Agent didn't respond in time. Possible dangling WebSocket on Teneo's side. Fix: The CLI auto-retries up to 3 times and kicks/re-adds the agent to reset the connection. If it still fails, try a different agent.

`Payment signing failed / Insufficient funds`

Cause: Wallet has no USDC on the required chain. Fix: Check balance with wallet-balance. Fund the wallet or try --chain with a different network.

`OOM on small instances`

Cause: npm install gets killed on low-memory VMs. Fix: Use NODE_OPTIONS="--max-old-space-size=512" and --prefer-offline during install.

Agent IDs with spaces fail

Cause: The SDK only allows [a-zA-Z0-9_-] in agent IDs. Fix: Always use the internal agent ID (e.g. x-agent-enterprise-v2), never the display name (e.g. "X Platform Agent").

Environment Variables

Variable	Required	Default	Description
`TENEO_PRIVATE_KEY`	No	Auto-generated	64 hex chars, no 0x prefix. Used for authentication and payment signing.
`TENEO_WS_URL`	No	`wss://backend.developer.chatroom.teneo-protocol.ai/ws`	Override the WebSocket endpoint.
`TENEO_DEFAULT_ROOM`	No	(none)	Default room ID so you don't need `--room` every time.
`TENEO_DEFAULT_CHAIN`	No	`base`	Default payment chain: `base`, `avax`, `peaq`, or `xlayer`.

The .env file in the current working directory is auto-loaded.

Available Agents

Agent	Commands	Description
Amazon	4	## Overview The Amazon Agent is a high-performance tool designed to turn massive...
Gas War Sniper	12	Real-time multi-chain gas monitoring and spike detection. Monitors block-by-bloc...
Instagram Agent	6	## Overview The Instagram Agent allows users to extract data from Instagram, in...
Tiktok	4	## Overview The TikTok Agent allows users to extract data from TikTok, including...
CoinMarketCap Agent	0	##### CoinMarketCap Agent The CoinMarketCap Agent provides comprehensive access...
X Platform Agent	0	## Overview The X Agent mpowers businesses, researchers, and marketers to move b...
Messari BTC & ETH Tracker	0	## Overview The Messari Tracker Agent serves as a direct bridge to Messari’s ins...

teneo-protocol-cli

teneo-protocol-cli — CLI Gateway for the Teneo Agent Network

What This Skill Teaches You

Prerequisites

Installation — Auto-Install If Missing

Step 1: Check if teneo-cli is available

Step 2: If NOT_INSTALLED, install globally

Step 3: Verify installation

Fallback: Run directly with npx

Authentication

1. Environment variable (highest priority)

2. Encrypted wallet file (auto-generated)

3. .env file (auto-loaded from current directory)

Wallet Security

Funding the wallet

Network connections

IMPORTANT: Always Show Status Updates

IMPORTANT: Agent Discovery & Room Limits

Finding Agents

Agent "Online" does not mean Reachable

Pre-Query Checklist

Room Rules

Command Reference

Agent Discovery

health

discover

list-agents

info

Agent Commands

command

quote

confirm

Room Management

rooms

room-agents

create-room

update-room

delete-room

add-agent

remove-agent

owned-rooms

shared-rooms

subscribe

unsubscribe