Flipside CLI

Query blockchain data, create AI agents, and build automated data pipelines.

First Steps

Always start by checking what's available in the user's organization:

1. Verify authentication and see the current org

flipside whoami

2. List available agents (names vary by org)

flipside agents list

3. List available skills

flipside skills list

Agent and skill names are organization-specific. Always run flipside agents list to discover what agents are available before trying to use them.

Golden Rule

Use Flipside agents for SQL queries. Don't write SQL from scratch—let the agents generate correct queries against Flipside's data warehouse.

One-shot query (no session memory)

flipside agents run / --message "Get the top 10 DEX swaps on Ethereum today"

Multi-turn conversation (maintains context between messages)

flipside chat create # get session ID flipside chat send-message --session-id "Get top DEX swaps on Ethereum" flipside chat send-message --session-id "Now filter to only Uniswap"

Always use --title when testing (makes sessions easier to find)

flipside agents run / --message "test query" --title "Testing from Claude Code"

Primary Workflows One-Shot Queries (agents run)

For single queries without session memory, use flipside agents run:

First, list available agents to find the right one

flipside agents list

Run a chat agent with a message

flipside agents run / --message "Show me the largest ETH transfers today"

Run a sub agent with structured JSON input

flipside agents run / --data-json '{"chain": "ethereum", "limit": 10}'

Add a title for easier session tracking

flipside agents run / --message "Query request" --title "My analysis"

IMPORTANT: Agent names MUST use the org/agent_name format. Get the exact names from flipside agents list.

Multi-Turn Conversations (chat)

For conversations that need session memory (follow-up questions, context from previous messages), use chat:

Create a new chat session

flipside chat create

Returns: Session ID: abc123...

Send messages to the session (maintains context)

flipside chat send-message --session-id "What were the top DEX swaps on Ethereum yesterday?"

Follow up (the session remembers previous context)

flipside chat send-message --session-id "Now show me the same for Arbitrum"

List your sessions

flipside chat list

Resume an existing session interactively

flipside chat resume

Use chat when you need:

Follow-up questions that reference previous answers Multi-step analysis where context matters Building on previous query results Running SQL Directly

For known queries, you can run SQL directly:

Create and execute a query

flipside query create "SELECT * FROM ethereum.core.fact_blocks LIMIT 10"

Execute an existing saved query

flipside query execute

Get results from a query run

flipside query-run result

Command Reference Agents flipside agents list # List available agents flipside agents init my_agent # Create agent YAML template flipside agents validate my_agent.agent.yaml # Validate before deploy flipside agents push my_agent.agent.yaml # Deploy agent flipside agents run / --message "..." # Run chat agent flipside agents run / --data-json '{}' # Run sub agent flipside agents describe / # Show agent details flipside agents pull / # Download agent YAML flipside agents delete / # Delete an agent

Chat flipside chat # Start interactive chat flipside chat --run # Chat about an automation run flipside chat resume # Resume previous chat flipside chat list # List chat sessions flipside chat send-message --session-id "x" # Programmatic message

Queries flipside query create "SELECT ..." # Create saved query flipside query list # List saved queries flipside query get # Get query details flipside query execute # Execute query (creates run) flipside query runs # List runs for a query flipside query-run result # Get query results flipside query-run status # Check run status flipside query-run poll # Poll until complete

Automations flipside automations list # List automations flipside automations init my_pipeline # Create automation YAML flipside automations validate # Validate before deploy flipside automations push # Deploy automation flipside automations run # Trigger automation flipside automations run -i '{"key":"val"}' # Run with inputs flipside automations runs list # List runs flipside automations runs result # Get run results

Skills flipside skills list # List available skills flipside skills init my_skill # Create skill YAML flipside skills push my_skill.skill.yaml # Deploy skill

Utilities flipside whoami # Show current user/org flipside --help # Full command help flipside --help # Help for specific command flipside update # Update CLI to latest version

When to Load References

Load the detailed reference files when you need:

AGENTS.md - Agent YAML schema, chat vs sub agents, deployment AUTOMATIONS.md - Pipeline steps, DAG edges, scheduling SKILLS.md - Creating reusable tool bundles TABLES.md - Common tables by chain (Ethereum, Solana, etc.) QUERIES.md - SQL patterns, result handling Creating New Agents

1. Create a template

flipside agents init my_agent

2. Edit the generated YAML file

my_agent.agent.yaml

3. Validate before deploying

flipside agents validate my_agent.agent.yaml

4. Deploy

flipside agents push my_agent.agent.yaml

Templates

Starter templates are available in assets/:

assets/agent.template.yaml - Basic agent config assets/automation.template.yaml - Basic automation config assets/skill.template.yaml - Basic skill config

Copy and customize these for new projects.

Troubleshooting

If a command fails:

Check authentication: flipside whoami Check CLI version: flipside --version and flipside update Use verbose mode: flipside --verbose Check JSON output for details: flipside --json