Skip to main content

Spider CLI - a verb-first command line for humans and AI agents

· 6 min read
Thibaut Raballand
Creator of Spider

Spider's UI is great when you want to see what has been captured.

But there is a long tail of moments where the UI is not the right tool:

  • a 3 a.m. incident where the goal is "did the call to the payments service actually go out?",
  • a CI job that needs to confirm a deployment generated the expected traffic,
  • an AI agent that needs to investigate a slow endpoint before suggesting a fix.

Those use cases want a CLI command. spider.

What it is​

spider is a standalone, statically-linked Go binary that talks to a Spider deployment over its REST API. It follows a kubectl-style verb-first structure: spider <verb> <resource>. No daemon, no extra runtime, no Python or Node prerequisite. Drop the binary on a path and it works.

It is designed for two audiences from day one:

  • Humans - operators and developers running ad-hoc queries from a terminal
  • AI agents - Claude Code, Codex, or any LLM-driven workflow that needs to introspect captured traffic on its own

That dual audience drives the design:

  • every output is structured JSON,
  • every command has a help text the LLM can read,
  • and every input that an agent might want to script (queries, time ranges, scopes) is a flag rather than buried in interactive prompts.

What you can do with it​

The command tree groups into four families. The patterns are the same across each:

Search and stats over captured traffic.

  • HTTP, PostgreSQL, TCP sessions, and raw packets.
  • Communications search.
  • Aggregate statistics.
  • Outlier detection for slow / large / anomalous calls.
  • Raw Elasticsearch aggregations for the cases that don't fit predefined statistics.

Cluster-wide network usage.

  • Two views of the per-minute traffic captured by Gocipher and enriched by the Controller:
    • a logical view (namespace + kind + name) for "which workloads talk to which?",
    • and a physical view (node + pod instance) for "which pod on which node sent what?".
  • Same search / stats / outliers / aggs verbs.

Capture control.

  • Discover Kubernetes namespaces and workloads visible to the active controller,
  • Then attach a whisperer to a target deployment and launch RECORDING.
  • The whole capture lifecycle accessible from command line.

Sharing.

  • Create a private link to a specific view (HTTP, PSQL, network usage…), with optional time window, Lucene filter, and team scope.
  • Or a public link with an OTP sent by email, an expiry, and an access filter that restricts what the recipient can see.

Authentication & profiles​

Authentication is profile-based, stored at ~/.spider/profiles.json (mode 0600).
Two auth types:

  • service_account (default; client-id + client-secret)
  • human (email + password).

Tokens are cached at ~/.spider/tokens.json and refreshed automatically when they expire.
Multiple profiles can coexist, scoped to different Spider instances, whisperers, controllers, or teams.

Where it adds value​

A few patterns it makes practical:

Quick traffic checks from a script.

  • A simple spider search http --query 'status_code:>=500' --start -10m answers "is something broken right now?" with one command.
  • The output is JSON, so jq or any structured-data tool consumes it directly.

Body inspection without round-tripping through the UI.

  • spider get http <id> res body fetches the raw response body from the server and decompresses it client-side - gzip, deflate, or br (brotli) - handled in the CLI.
  • Pipe to a file, run a diff, feed it to a parser.
  • This shortcuts the "open the UI, find the row, copy the body" loop.

Shareable links from CI.

  • When a load test or scenario script finishes, it can call spider add link --view http --query "..." --start <t1> --stop <t2> --public --expiry 24h --emails reviewer@team.com and post the resulting URL straight into the run report.
  • Anyone on the access list can land directly in the UI on the right time window with the right filters applied.

Coverage check before attaching a new whisperer.

  • Four commands - spider show namespaces, spider show collection, spider search attachments,spider show sidecars - answer "is a whisperer already covering this workload?" before proposing a new attach.
  • This makes the "agent decides whether to capture" decision tractable.

Long-tail aggregations.

  • The spider aggs verb takes a raw Elasticsearch aggregation JSON.
  • For the cases that the predefined stats don't cover - "top 10 templates by p99 latency where status is 500, grouped by host", say - you write the aggregation once and run it from anywhere.

What this looks like for an AI agent​

This is the more interesting half of the audience - and it has its own post.

The short version: a Claude Code plugin (spider, in the spider-analyzer marketplace) wraps the CLI with purpose-built skills and agents for the recurring investigation patterns.

  1. The human describes a problem,
  2. the plugin picks the right command sequence,
  3. and Claude returns a structured finding with a shareable Network-View link.

The full story - what the plugin contains, why purpose-built skills beat raw CLI access, and how it composes with the Spider-mon plugin - is in Spider's Claude Code plugins.

Installation​

The CLI is published as a .xz-compressed binary for Linux, macOS, and Windows, on both amd64 and arm64, from https://repository.floocus.com/bin/spider-cli-<os>-<arch>/<version>/spider.xz. Statically linked (CGO_ENABLED=0), so the Linux build runs on glibc and musl (Alpine) without changes, and without dependencies.

Full install instructions, the complete command reference, profile setup, and the network usage views are documented at /docs/tools/spider-cli.

The Claude Code plugin install (one-liner from inside Claude Code) and the available skills / agents are documented at /docs/tools/spider-claude-plugin.

Closing​

A CLI is a small thing.

But the right CLI shifts what is possible: tasks that were UI-only become scriptable, scripted tasks become composable, and composable tasks become things an AI agent can run on its own.

spider is the entry point that the rest of this release's tooling - the Spider Claude plugin, the Spider-mon CLI, the Spider-mon plugin - assumes exists.

Feedback, feature requests, and edge cases that aren't covered yet are all welcome.