teneo-cli

Original：🇺🇸 English
Translated

Teneo CLI — query 400+ AI agents on the Teneo Protocol network from the terminal. Discover agents, manage rooms, handle x402 USDC micropayments, and auto-generate encrypted wallets. Use when the user needs real-time data (social media profiles, hotel search, crypto prices, gas fees, Amazon products, news) or multi-agent workflows.

5installs
Sourceteneoprotocolai/teneo-skills
Added on

NPX Install

npx skill4agent add teneoprotocolai/teneo-skills teneo-cli

Tags

Translated version includes tags in frontmatter
teneo-cliai-agent-networkx402-paymentswallet-managementreal-time-data-retrieval

SKILL.md Content

View Translation Comparison →

teneo-cli — Query AI Agents on the Teneo Protocol Network

Purpose

Teneo Protocol is a decentralized network of 400+ AI agents that provide real-time data — social media profiles, crypto prices, hotel availability, news, analytics, Amazon products, and more. Agents are paid per query in USDC via x402 micropayments.
This is a CLI tool (TypeScript/Node.js) for querying agents from the terminal. Run bash commands to discover agents, send queries, manage rooms, and handle payments. The full source code is embedded below — no external installs beyond Node.js.
What you can do:
  1. Discover every agent on the network — commands, pricing, capabilities
  2. Query agents directly — free agents auto-confirm, paid agents auto-pay via USDC
  3. Manage rooms — create rooms, add/remove agents (max 5 per room)
  4. Handle payments — automatic USDC on Base, Peaq, Avalanche, or X Layer
  5. Sign transactions — handle on-chain requests from agents (swaps, transfers)
  6. Manage wallets — encrypted wallet storage, balance checks, withdrawals
Use this skill when you need real-time data from a Teneo agent — social media (X/Twitter, Instagram, TikTok, LinkedIn), hotel search, crypto prices, gas fees, Amazon products, news, and more.

Prerequisites

  • Node.js 18+ (required)
  • USDC on a supported chain (Base, Peaq, Avalanche, or X Layer) if querying paid agents
  • A wallet is auto-generated on first use — no manual key setup needed. You can optionally set 
    TENEO_PRIVATE_KEY
    to use an existing key.

Installation — MUST Run Before First Use

IMPORTANT: This skill provides its OWN CLI. Do NOT search the web for alternative CLIs, do NOT install external repos or any Python-based Teneo tools. Those are completely unrelated projects.
Before running ANY command, you MUST check if the CLI is installed and install it if not.

Step 1: Check if the CLI exists

bash
test -f ~/teneo-skill/teneo && echo "INSTALLED" || echo "NOT_INSTALLED"

Step 2: If NOT_INSTALLED, install with a single command

bash
npx -y @teneo-protocol/cli
This installs the CLI to 
~/teneo-skill/
and sets up all skills automatically.

Step 3: Verify installation

bash
~/teneo-skill/teneo health
You should see JSON output with connection status.

How to Run Commands

All commands are run as bash commands:
bash
~/teneo-skill/teneo <command> [arguments] [options]
Example:
bash
~/teneo-skill/teneo list-agents
~/teneo-skill/teneo info x-agent-enterprise-v2
~/teneo-skill/teneo command "x-agent-enterprise-v2" "user @elonmusk" --room <roomId>
All output is JSON to stdout. Parse the JSON to extract results.

Authentication

The CLI auto-generates an encrypted wallet on first use — no manual key setup required. Just install and start querying. The wallet is used for:
  • Authentication — signs the WebSocket handshake to prove identity on Teneo
  • Payment — signs x402 USDC transactions to pay agents
  • TX signing — auto-signs on-chain transactions (approvals, swaps, bridges) requested by agents

Bring your own key (optional)

If you already have a wallet, you can provide it instead of auto-generating:

Environment variable (highest priority)

bash
export TENEO_PRIVATE_KEY=<your-64-hex-char-private-key>

.env file (auto-loaded from ~/teneo-skill/)

bash
echo "TENEO_PRIVATE_KEY=<your-64-hex-char-private-key>" > ~/teneo-skill/.env

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

  1. Run 
    ~/teneo-skill/teneo wallet-address
    — the wallet address is printed
  2. Send USDC to that address on Base, Peaq, Avalanche, or X Layer
  3. The CLI detects the funder automatically and locks withdrawals to that address only

Network connections

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:
  1. Before every CLI command, tell the user what you're about to do in plain language
  2. After each step completes, confirm it before moving to the next step
  3. If something takes more than a few seconds, send a "still waiting..." or "processing..." update
  4. 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:
  1. Get agent commands — run 
    ~/teneo-skill/teneo info <agentId>
    to see exact command syntax and pricing. Never guess commands.
  2. Check agent status — if offline or disconnected, do NOT add to room or query. Find an alternative.
  3. Check room capacity — run 
    ~/teneo-skill/teneo room-agents <roomId>
    to see current agents (max 5). If full, remove one or create a new room.
  4. Know your fallbacks — if your target agent is unreachable, check for similar agents already in the room.
  5. 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:
  1. Maximum 5 agents per room. A room can hold at most 5 agents at a time.
  2. You can only query agents that are in your room. If an agent is not in the room, commands to it will fail.
  3. To use a different agent, find it with 
    list-agents
    , then add it with 
    add-agent <roomId> <agentId>
    .
  4. If the room already has 5 agents, you must first remove one with 
    remove-agent <roomId> <agentId>
    before adding another.
  5. 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 -->

Command Reference

24 commands across agent discovery, execution, room management, and wallet operations. All commands return JSON to stdout.
AGENT DISCOVERY
  ~/teneo-skill/teneo health                         Check connection health
  ~/teneo-skill/teneo discover                       Full JSON manifest of all agents, commands, and pricing — designed for AI agent consumption
  ~/teneo-skill/teneo list-agents                    List all agents on the Teneo network
  ~/teneo-skill/teneo info <agentId>                 Show agent details, commands, and pricing

AGENT COMMANDS
  ~/teneo-skill/teneo command <agent> <cmd>          Direct command to agent (use internal agent ID, not display name)
  ~/teneo-skill/teneo quote <message>                Check price for a command (does not execute)

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

WALLET MANAGEMENT
  ~/teneo-skill/teneo wallet-init                    Show wallet status
  ~/teneo-skill/teneo wallet-address                 Show wallet public address
  ~/teneo-skill/teneo wallet-export-key              Export private key (DANGEROUS)
  ~/teneo-skill/teneo wallet-balance                 Check USDC and native token balances on supported chains

Agent Discovery

health

Check connection health
bash
~/teneo-skill/teneo health

discover

Full JSON manifest of all agents, commands, and pricing — designed for AI agent consumption
bash
~/teneo-skill/teneo discover

list-agents

List all agents on the Teneo network
bash
~/teneo-skill/teneo list-agents [--online] [--free] [--search <keyword>]
OptionDescriptionDefault
--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
bash
~/teneo-skill/teneo info <agentId>
ArgumentRequiredDescription
agentId
Yes-

Agent Commands

command

Direct command to agent (use internal agent ID, not display name)
bash
~/teneo-skill/teneo command <agent> <cmd> [--room <roomId>] [--timeout <ms>] [--chain <chain>]
ArgumentRequiredDescription
agent
YesInternal agent ID (e.g. x-agent-enterprise-v2)
cmd
YesCommand string: {trigger} {argument}
OptionDescriptionDefault
--room <roomId>
--
--timeout <ms>
Response timeout120000
--chain <chain>
--

quote

Check price for a command (does not execute)
bash
~/teneo-skill/teneo quote <message> [--room <roomId>] [--chain <chain>]
ArgumentRequiredDescription
message
Yes-
OptionDescriptionDefault
--room <roomId>
--
--chain <chain>
--

Room Management

rooms

List all rooms
bash
~/teneo-skill/teneo rooms

room-agents

List agents in room
bash
~/teneo-skill/teneo room-agents <roomId>
ArgumentRequiredDescription
roomId
Yes-

create-room

Create room
bash
~/teneo-skill/teneo create-room <name> [--description <desc>] [--public]
ArgumentRequiredDescription
name
Yes-
OptionDescriptionDefault
--description <desc>
--
--public
Make room publicfalse

update-room

Update room
bash
~/teneo-skill/teneo update-room <roomId> [--name <name>] [--description <desc>]
ArgumentRequiredDescription
roomId
Yes-
OptionDescriptionDefault
--name <name>
--
--description <desc>
--

delete-room

Delete room
bash
~/teneo-skill/teneo delete-room <roomId>
ArgumentRequiredDescription
roomId
Yes-

add-agent

Add agent to room
bash
~/teneo-skill/teneo add-agent <roomId> <agentId>
ArgumentRequiredDescription
roomId
Yes-
agentId
Yes-

remove-agent

Remove agent from room
bash
~/teneo-skill/teneo remove-agent <roomId> <agentId>
ArgumentRequiredDescription
roomId
Yes-
agentId
Yes-

owned-rooms

List rooms you own
bash
~/teneo-skill/teneo owned-rooms

shared-rooms

List rooms shared with you
bash
~/teneo-skill/teneo shared-rooms

subscribe

Subscribe to public room
bash
~/teneo-skill/teneo subscribe <roomId>
ArgumentRequiredDescription
roomId
Yes-

unsubscribe

Unsubscribe from room
bash
~/teneo-skill/teneo unsubscribe <roomId>
ArgumentRequiredDescription
roomId
Yes-

Wallet Management

wallet-init

Show wallet status
bash
~/teneo-skill/teneo wallet-init

wallet-address

Show wallet public address
bash
~/teneo-skill/teneo wallet-address

wallet-export-key

Export private key (DANGEROUS)
bash
~/teneo-skill/teneo wallet-export-key

wallet-balance

Check USDC and native token balances on supported chains
bash
~/teneo-skill/teneo wallet-balance [--chain <chain>]
OptionDescriptionDefault
--chain <chain>
Specific chain (baseavax
<!-- /COMMAND_REFERENCE -->

Pricing Model

Every command has a pricing model. Check 
pricePerUnit
and 
taskUnit
in agent details before executing.
FieldTypeDescription
pricePerUnit
numberUSDC amount per unit. 
0
or absent = free.
taskUnit
string
"per-query"
= flat fee per call. 
"per-item"
= price x item count.

Supported Payment Networks

NetworkChain IDUSDC Contract
Base
eip155:8453
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Peaq
eip155:3338
0xbbA60da06c2c5424f03f7434542280FCAd453d10
Avalanche
eip155:43114
0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E
X Layer
eip155:196
0x74b7F16337b8972027F6196A17a631aC6dE26d22

Payment flow

  1. You send a 
    command
    to an agent
  2. The SDK requests a price quote from the agent
  3. If free (price=0), auto-confirms immediately
  4. If paid, auto-signs an x402 USDC payment and confirms
  5. Agent processes the request and returns data
If funds are insufficient on the default chain, try a different chain with 
--chain
.

Typical Workflow

  1. Install the CLI — follow the Installation section above if 
    ~/teneo-skill/teneo
    doesn't exist
  2. Ensure wallet is funded — run 
    ~/teneo-skill/teneo wallet-balance
    to check USDC. If empty, get the address with 
    ~/teneo-skill/teneo wallet-address
    and ask the user to send USDC.
  3. Discover agents — run 
    ~/teneo-skill/teneo list-agents
    or 
    ~/teneo-skill/teneo info <agentId>
    to see commands and pricing
  4. Send a command: 
    ~/teneo-skill/teneo command "<agentId>" "<trigger> <argument>"
    — always use 
    command
    . It handles everything: auto-resolves room, auto-adds agent, auto-pays, auto-signs transactions.
  5. Swap agents as needed — if an agent is dead, find an alternative.
IMPORTANT: Always use 
command
. It handles everything: payment, room management, agent autosummon, TX signing, and multi-step flows (swaps, approvals, bridges) automatically.

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: Install the CLI (if not already installed)

bash
test -f ~/teneo-skill/teneo && echo "INSTALLED" || echo "NOT_INSTALLED"
If NOT_INSTALLED, follow the Installation section above.

Step 2: Discover what's available

bash
~/teneo-skill/teneo discover
Cache this output. It contains a full manifest of all agents, commands, and pricing.

Step 3: 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 4: Execute the query

bash
~/teneo-skill/teneo command "<agentId>" "<trigger> <argument>"
Room is auto-resolved. Agent is auto-added if not in room. Payment is auto-signed.

Step 5: Parse the response

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

Step 6: Handle errors

ErrorMeaningAction
"agent not found or disconnected"
Agent offline in your roomFind alternative agent, or kick and re-add
"room is full"
5 agents already in roomRemove one or create new room
"insufficient funds"
Wallet lacks USDCCheck balance, fund wallet, or try different chain
"timeout"
No response in timeRetry once, then try different agent
"All N attempts failed"
SDK connection failedCheck network, wait and retry
The 
command
handler automatically resolves rooms, adds agents, and swaps out agents when the room is full. No manual room management needed.

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

VariableRequiredDefaultDescription
TENEO_PRIVATE_KEY
No(auto-generated)64 hex chars, no 0x prefix. Auto-generated on first use if not set.
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 
~/teneo-skill/
is auto-loaded.

Deploying Your Own Agent

To build and deploy your own agent on the Teneo network and earn USDC per query, use the 
teneo-agent-deployment
skill.

Links

<!-- AGENTS_LIST -->

Available Agents

AgentCommandsDescription
Amazon4## Overview The Amazon Agent is a high-performance tool designed to turn massive...
Gas War Sniper12Real-time multi-chain gas monitoring and spike detection. Monitors block-by-bloc...
Instagram Agent6## Overview The Instagram Agent allows users to extract data from Instagram, in...
Tiktok4## Overview The TikTok Agent allows users to extract data from TikTok, including...
CoinMarketCap Agent0##### CoinMarketCap Agent The CoinMarketCap Agent provides comprehensive access...
Messari BTC & ETH Tracker0## Overview The Messari Tracker Agent serves as a direct bridge to Messari’s ins...
Squid Router0# Squid Router Agent Cross-chain token swap agent powered by Squid Router. Swap...
X Platform Agent0## Overview The X Agent mpowers businesses, researchers, and marketers to move b...
<!-- /AGENTS_LIST -->