CLI Reference
All commands use koyal as the binary name. Implemented with clap derive in src/lib.rs, dispatched by src/main.rs.
Run koyal --help or koyal <command> --help at any time.
Core
koyal doctor
Check installation and harness state.
koyal doctor
Output:
{"status":"ok","version":"0.1.0","harness":"rust","gateway":8790}
koyal gateway
Start the HTTP gateway and serve the web dashboard.
koyal gateway
koyal gateway --host 127.0.0.1 --port 8790
koyal gateway --host 0.0.0.0 --port 9090
| Flag | Default | Description |
|---|---|---|
--host | 127.0.0.1 | Bind host |
--port | 8790 | Bind port |
On startup prints:
[koyal] Gateway http://127.0.0.1:8790/api
[koyal] Dashboard http://127.0.0.1:8790/
koyal dashboard
Web dashboard controls.
koyal dashboard open # open browser
koyal dashboard url # print URL
koyal dashboard status # ping gateway, print JSON status
koyal dashboard open --port 9090 # non-default port
| Subcommand | Description |
|---|---|
open | Open dashboard in default browser (open / xdg-open / start) |
url | Print http://host:port/ |
status | Hit /api/health, print running/not-running JSON |
koyal tui
Launch the ratatui terminal UI.
koyal tui
Keybindings: q quit · r refresh · ←→ switch tabs · t trigger tick.
koyal agent-tick
Run one trading-agent tick and print the result as JSON.
koyal agent-tick --agent solana_jupiter
koyal agent-tick --agent solana_jupiter --propose
koyal agent-tick --agent solana_jupiter --propose --new-session
| Flag | Default | Description |
|---|---|---|
--agent | solana_jupiter | Agent ID (maps to trading_agents/<id>/) |
--propose | false | Allow proposal creation if strategy rules pass |
--new-session | false | Start a new trading session |
Executor Commands
koyal executor list
koyal executor list --agent solana_jupiter
koyal executor stop
koyal executor stop --id ex_solana_jupiter_1_1700000000 --reason "manual stop"
koyal executor reconcile
koyal executor reconcile --id ex_solana_jupiter_1_1700000000
koyal executor snapshot
koyal executor snapshot --agent solana_jupiter
AI Commands
koyal ai providers
List configured AI providers and their status.
koyal ai providers
koyal ai health
Run connectivity health checks on all configured providers.
koyal ai health
koyal ai budget
Show token usage summary.
koyal ai budget
koyal ai budget --agent solana_jupiter --limit 100
| Flag | Default | Description |
|---|---|---|
--agent | all | Filter by agent ID |
--limit | 50 | Max records to show |
koyal ai profile-list
List encrypted auth profiles.
koyal ai profile-list
Trade Commands
koyal trade list
List all trade proposals.
koyal trade list
koyal trade report
Show trade summary report.
koyal trade report
koyal trade jupiter-order
Preview a Jupiter swap order (does not execute).
koyal trade jupiter-order \
--input So11111111111111111111111111111111111111112 \
--output EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
--amount 1000000000
Wallet Commands
koyal wallet balance
Show wallet balance.
koyal wallet balance
koyal wallet address
Show wallet address.
koyal wallet address
koyal wallet generate
Generate a new wallet with BIP39/BIP32 derivation.
koyal wallet generate --chain solana
koyal wallet generate --chain evm --index 1
koyal wallet generate --chain solana --mnemonic "word1 word2 ..."
| Flag | Default | Description |
|---|---|---|
--chain | solana | Chain: solana, evm |
--index | 0 | Derivation index |
--mnemonic | random | BIP39 seed phrase |
Halt Commands
koyal halt status
Show global halt state.
koyal halt status
koyal halt on
Enable trading halt — blocks all proposal execution.
koyal halt on
koyal halt on --reason "flash crash detected"
koyal halt off
Disable trading halt.
koyal halt off
Memory Commands
koyal memory summary
Show agent memory summary.
koyal memory summary
koyal memory summary --agent solana_jupiter
koyal memory search
Search agent memory with FTS5 full-text search.
koyal memory search --query "sol rally"
koyal memory search --query "loss" --agent solana_jupiter
Agent Commands
koyal agent list
List all managed agents.
koyal agent list
koyal agent create
Create a new managed agent.
koyal agent create --id trader1 --name "Trader One" --kind trading
| --kind values | trading, research, operations, assistant, custom |
koyal agent get
Get agent details.
koyal agent get --id trader1
koyal agent delete
Delete an agent.
koyal agent delete --id trader1
Bot Commands
koyal bot list
List bots for an agent.
koyal bot list --agent trader1
koyal bot create
Create a trading bot.
koyal bot create --id bot1 --agent trader1 --name "Jupiter Bot" --venue jupiter
koyal bot setup
Create a bot with strategy and loop (the recommended path).
koyal bot setup \
--agent trader1 \
--name jup_sol_bot \
--strategy "Conservative Jupiter swaps on Solana. Max 2% portfolio per trade." \
--loop price_watcher
| Flag | Default | Description |
|---|---|---|
--agent | required | Agent ID |
--name | required | Bot name |
--strategy | required | Strategy description (fed to agent) |
--loop-blueprint | price_watcher | Loop blueprint to attach |
--extra | "" | Extra context passed to strategy |
koyal bot transition
Change bot lifecycle state.
koyal bot transition --id bot1 --target live
koyal bot transition --id bot1 --target paused
States: paper → live → paused → paper
koyal bot assign-wallet
Assign a wallet to a bot.
koyal bot assign-wallet --bot-id bot1 --wallet wallet_id_here
Loop Commands
koyal loop list
List agent loops.
koyal loop list --agent trader1
koyal loop blueprints
List available loop blueprints.
koyal loop blueprints
Available blueprints: market_pulse, trade_watch, portfolio_rebalance, wallet_monitor, price_watcher, onchain_scanner.
koyal loop create
Create a loop from a blueprint.
koyal loop create --agent trader1 --blueprint price_watcher
koyal loop toggle
Enable or disable a loop.
koyal loop toggle --id loop_id_here
Skill Commands
koyal skills list
List all available skills.
koyal skills list
koyal skills info
Show skill details.
koyal skills info --name trading-agent-builder
koyal skills pin / koyal skills unpin
Pin a skill to prevent auto-archive.
koyal skills pin --name risk-guardrails
koyal skills unpin --name risk-guardrails
koyal skills refresh
Force refresh skill metadata.
koyal skills refresh
Vault Commands
The vault is the single source of truth (bible) for each agent.
koyal vault agents
List agents with a vault.
koyal vault agents
koyal vault bible
Read the full composed bible (soul + instructions + memories + learnings + bot configs).
koyal vault bible --agent trader1
koyal vault snapshot
Create a git-friendly snapshot of the entire bible.
koyal vault snapshot --agent trader1
koyal vault soul-read / koyal vault soul-write
Read or write soul.md.
koyal vault soul-read --agent trader1
koyal vault soul-write --agent trader1 --content "I trade conservatively."
koyal vault instructions-read / koyal vault instructions-write
Read or write instructions.md.
koyal vault instructions-read --agent trader1
koyal vault instructions-write --agent trader1 --content "Rule 1: ..."
koyal vault memories
List agent memories.
koyal vault memories --agent trader1
Telegram Commands
koyal telegram status
Show Telegram integration status.
koyal telegram status
koyal telegram senders
List paired Telegram senders.
koyal telegram senders
koyal telegram pair
Pair a Telegram sender to an agent channel.
koyal telegram pair --sender-id 123456789 --channel trader1
koyal telegram block
Block a Telegram sender.
koyal telegram block --sender-id 123456789
koyal telegram provision-channel
Create a new Telegram notification channel.
koyal telegram provision-channel --chat-id -100123456789 --label "Alerts"