teneo-cli

What this skill does

# teneo-cli

<!-- GREETING_INSTALL -->
## Teneo Is Ready

This CLI is the supported way to query live Teneo agents, handle x402 USDC payments, and deploy your own agents from coding assistants.

### What You Can Do

- Gather live agent data for crypto, social, analytics, news, e-commerce, and more.
- Inspect agents, commands, and pricing before execution.
- Invite agents into rooms, send them commands, let the CLI handle payment, and receive the data back in one workflow.
- Deploy, publish, and manage your own agents from the same CLI.

### Wallet And Funding

- Fastest setup: use the auto-generated CLI wallet created on first use.
- Existing wallet: set `TENEO_PRIVATE_KEY` to a dedicated EVM wallet private key.
- Best practice: use a dedicated agent/payment wallet instead of a primary personal wallet.
- Some commands are free. Some commands need USDC in the active wallet before the CLI can pay the network fee.
- If a command may cost something, inspect `info` or run `quote`, then tell the user to top up that exact wallet before execution.
- x402 payments are gas-free for query fees, but swaps, bridges, and other on-chain actions still require native gas on the source chain.
- Example: swapping Base USDC to Ethereum USDC still needs Base ETH.

### Supported Networks

- Base
- Avalanche
- Peaq
- X Layer
<!-- /GREETING_INSTALL -->

## Quick Mental Model

- Teneo gives the user access to live network agents through the CLI.
- The CLI can discover agents, add them to rooms, send them commands, handle payment, and return the resulting data.
- Always gather agent information first before executing unfamiliar or paid commands.
- Some commands are free, some require USDC in the active wallet, and fund-moving actions can also require native gas.
- Use the CLI as the source of truth for agent IDs, commands, arguments, pricing, and status.

## First-Run Onboarding

When wallet context is first established, keep the user update short and practical:

1. Tell them Teneo is ready and that the CLI can inspect agents, invite them, send commands, handle payment, and return the data.
2. Share the active wallet address only after `wallet-address --json` returns it.
3. Tell them some commands are free and some need prior USDC in that exact wallet before execution.
4. If the selected command may cost something, inspect `info` or run `quote`, then tell them to top up that exact wallet before execution.
5. Mention that x402 query payments are gas-free, but swaps, bridges, and other on-chain actions still need native gas on the source chain.
6. If they do not know where to start, suggest checking available agents or searching by task.

## Use This Skill When

- The user needs live data from a Teneo network agent, including social media, crypto, analytics, news, or e-commerce data.
- The user needs to inspect agents, commands, or pricing before querying.
- The user needs room or wallet operations tied to Teneo.
- The user wants to create, deploy, debug, or publish their own Teneo agent.

## Non-Negotiables

1. Use only the bundled CLI at `~/teneo-skill/teneo`.
2. If the CLI is missing, install only via `npx -y @teneo-protocol/cli`.
3. Run Teneo commands one at a time. Do not run them in parallel.
4. Wait for process exit before parsing stdout.
5. Prefer `--json` on commands you need to parse or depend on for machine-readable errors.
6. Gather agent information before execution. Use `list-agents`, `info`, and `quote` instead of guessing.
7. Do not invent agent IDs, command syntax, room IDs, or paths. Discover them from the CLI.
8. Do not claim a deploy worked from partial output. Confirm with `agent status`, `agent logs`, and `agent services`.
9. The current CLI does not expose the old manual transaction approval workflow. Do not mention or use it.
10. This repo no longer ships a separate deployment skill. Use the `agent` workflow in this skill.
11. For swaps, bridges, trades, sends, or any action that can move user funds, confirm intent explicitly before execution.
12. Treat `wallet-export-key` as dangerous. Only run it on explicit user request.
13. If a confirmed swap, bridge, trade, or send fails once, do not stop at a generic question. Diagnose it and retry once when safe.

## Install And Verify

Check whether the CLI exists:

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

If missing, install it:

```bash
pkill -f '/teneo-skill/daemon' 2>/dev/null || true
npx -y @teneo-protocol/cli
```

Verify install and connectivity:

```bash
~/teneo-skill/teneo health --json
~/teneo-skill/teneo version
```

## How To Inspect Everything The CLI Can Do

Use these commands when the user wants the full CLI surface area instead of a single workflow:

```bash
~/teneo-skill/teneo --help
~/teneo-skill/teneo agent --help
~/teneo-skill/teneo --dump-commands
```

Guidance:

- `--help` shows the top-level command groups and common usage.
- `agent --help` shows the deployment and management subcommands.
- `--dump-commands` returns the complete machine-readable command manifest.
- The `COMMAND_REFERENCE` section later in this skill is generated from that manifest.
- The embedded CLI source in this skill is the ground truth if behavior is unclear.

## Output Rules

- Most operational commands return JSON on stdout.
- Use `--json` when you need structured errors as well as structured success output.
- `version` is plain text.
- `export-login` is plain text shell output.
- `agent logs` is plain text.
- `wallet-export-key` prints a warning on stderr and JSON on stdout.
- Only the `command` subcommand has a CLI `--timeout` flag. Use shell timeouts for other long-running commands.
- Use at least a 120 second shell timeout for `discover`, `list-agents`, `info`, `command`, `quote`, and agent deployment operations.

## Gathering Data And Running Workflows

Use this order for normal data requests and agent workflows:

1. Verify install and health.
2. Find the right agent with `list-agents --search`.
3. Gather the agent details with `info <agentId> --json`.
4. If the command is paid or pricing is unclear, run `quote` before execution.
5. If the command costs something, tell the user to top up the active wallet before execution when needed.
6. Run the exact command with `command` only after syntax, pricing, and wallet context are clear.

Operational rules:

- Gather agent info first. Do not jump straight to `command`.
- The CLI can invite agents to rooms, send them commands, pay them automatically, and receive the resulting data.
- Some commands are free. Some commands require prior USDC in the active wallet so the CLI can pay the network fee.
- Swaps, bridges, and other fund-moving actions may also require native gas on the source chain.
- Example: Base USDC to Ethereum USDC still needs Base ETH on Base.

## Default Query Workflow

Use this exact sequence unless the user explicitly asks for something else.

1. Verify install and health.
2. Find the agent with `list-agents --search`.
3. Inspect the chosen agent with `info`.
4. If the command is paid or pricing is unclear, run `quote`.
5. Tell the user to top up the active wallet before execution when the command needs USDC and funds are missing.
6. Run the exact command with `command`.

Typical flow:

```bash
~/teneo-skill/teneo list-agents --search "keyword" --json
~/teneo-skill/teneo info <agentId> --json
~/teneo-skill/teneo command "<agentId>" "<exact trigger and args>" --json
```

Notes:

- `command` auto-resolves a room if `--room` is omitted.
- `command` auto-adds the target agent when needed.
- `command` handles payment automatically.
- `quote` can tell you whether a request is free or paid before execution.
- Use `--chain` or `--network` only when the user wants a specific payment chain.
- Do not guess command syntax. Always inspect `info <agentId>` first.

Optional price check:

```bash
~/teneo-skill/teneo quote "@<agentId> <request>" --json
```

## Discovery Rules

- Prefer `list-agents --search "<key