Javier Leandro Arancibia

Posted on May 26 • Originally published at github.com

SuperCLI Zig: A 260KB Binary That AI Agents Love

#cli #ai #zig #devtools

AI agents struggle with CLI tools. Every tool has different flags, output formats, and installation methods. SuperCLI fixes this with a unified interface for 3,300+ tools — and now there's a Zig implementation that's perfect for agents.

The Problem with CLIs and AI

When an AI agent tries to use a CLI tool, it faces several challenges:

Inconsistent interfaces: Each tool has different flag syntax
Unpredictable output: Human-readable text is hard for agents to parse
Installation complexity: Different package managers, dependencies, and setup steps
No self-documentation: Agents can't discover capabilities without external docs

Enter sc-zig: The Agent-Friendly SuperCLI

SuperCLI Zig (sc-zig) is a single-binary implementation of SuperCLI written in Zig. It's designed specifically for AI agents:

# Install single binary (~260KB, no Node.js required)
curl -sL https://github.com/javimosch/supercli/releases/download/v0.1.0-zig/install.sh | bash

# Agent-friendly bootstrap — self-documenting
sc-zig --json

The bootstrap JSON tells agents everything they need to know:

{
  "version":"1.0",
  "mode":"agent_bootstrap",
  "name":"supercli-zig",
  "workflow":"discover -> inspect -> execute",
  "first_steps":[
    "sc-zig plugins explore --name <topic> --json",
    "sc-zig plugins install <name>",
    "sc-zig commands --query <keyword> --json",
    "sc-zig inspect <ns> <res> <act> --json",
    "sc-zig <ns> <res> <act> --flag val --json"
  ],
  "memory_workflow":{
    "step1":"sc-zig plugins explore --name memory --json",
    "step2":"sc-zig plugins install agentmemory-cli",
    "step3":"sc-zig agentmemory-cli memory save --text \"my name is Javi\" --project default --json",
    "step4":"sc-zig agentmemory-cli memory search --query Javi --json"
  }
}

Why Agents Love sc-zig

1. Single Binary, No Dependencies

Size: ~260KB (vs ~50MB for Node.js version with node_modules)
Dependencies: None (just curl + chmod to install)
Startup: Instant (no Node.js runtime overhead)

2. Self-Documenting Bootstrap

Agents get complete workflow guidance without external documentation:

Built-in workflow examples
Memory workflow for persistent context
Feature notes explaining limitations
First steps for common tasks

3. Agent Guidance When Things Go Wrong

When plugin searches return no results, agents get actionable help:

{
  "total":0,
  "returned":0,
  "plugins":[],
  "suggestion":"Run: sc-zig plugins update"
}

4. Fixed Arg Parsing

Previous CLI tools had bugs where --flag value was parsed incorrectly. sc-zig handles both formats:

# Both work correctly
sc-zig plugins explore --name memory --json
sc-zig plugins explore --name=memory --json

5. Positional Arguments

Commands with positional arguments work correctly:

# Query is a positional arg (defined in plugin.json)
sc-zig agentmemory-cli memory search --query "search term" --json

Complete Agent Workflow Example

Here's how an AI agent would use sc-zig to remember context across sessions:

# 1. Discover memory plugin
sc-zig plugins explore --name memory --json
# → {"total":19,"returned":19,"plugins":[...]}

# 2. Install memory plugin
sc-zig plugins install agentmemory-cli
# → {"ok":true,"plugin":"agentmemory-cli",...}

# 3. Save memory
sc-zig agentmemory-cli memory save --text "User prefers dark mode" --project myproject --json
# → {"data":{"raw":"saved memory ba35bb70-ca7e-44c3-9f48-7af98c29f7a1"}}

# 4. Search memory
sc-zig agentmemory-cli memory search --query "dark mode" --json
# → {"data":{"raw":"ba35bb70  User prefers dark mode"}}

Real-World Validation

We tested sc-zig with simulated agent workflows:

✅ Discovery: Agents can find and run sc-zig without prior knowledge
✅ Bootstrap: Agents get self-documenting JSON with workflow guidance

✅ Plugin explore: Agents can discover plugins (19 memory plugins found)
✅ Arg parsing: Both --flag value and --flag=value work correctly
✅ Guidance: Agents receive actionable help when no results found
✅ Plugin catalog: Successfully fetched 3,302 plugins from GitHub
✅ Memory workflow: Complete save → search → list → forget workflow validated

Performance Benefits

Metric	sc-zig	Node.js sc
Binary size	~260KB	~50MB
Dependencies	None	Node.js runtime
Startup time	Instant	~100ms
Memory usage	Minimal	Node.js overhead

When to Use sc-zig vs Node.js sc

Use sc-zig when:

Agent workflows (single binary, no dependencies)
Performance-critical scenarios
Environments without Node.js
Minimal footprint required

Use Node.js sc when:

Need MCP server or HTTP adapter
Developing plugins
Need full feature parity

Getting Started

# Install sc-zig
curl -sL https://github.com/javimosch/supercli/releases/download/v0.1.0-zig/install.sh | bash

# Or manual install
curl -sL https://github.com/javimosch/supercli/releases/download/v0.1.0-zig/sc-zig-linux-amd64 -o ~/.local/bin/sc-zig && chmod +x ~/.local/bin/sc-zig

# Try it out
sc-zig --json
sc-zig plugins explore --name docker --json

The Future of Agent-Ready CLIs

sc-zig represents a shift toward agent-first CLI design:

Self-documenting: No external docs required
Predictable: Consistent JSON output
Forgiving: Helpful error messages and suggestions
Minimal: Single binary, no runtime dependencies
Fast: Native performance for instant agent response

As AI agents become more prevalent in development workflows, CLI tools need to evolve. sc-zig shows how it's done.

Try sc-zig Today

Give your AI agents the CLI tool they deserve:

curl -sL https://github.com/javimosch/supercli/releases/download/v0.1.0-zig/install.sh | bash

Your agents will thank you.

Resources:

Tags: #cli #artificialintelligence #zig #devtools

DEV Community