DEV Community: Javier Leandro Arancibia

Introducing SuperCLI: A Config-Driven, AI-Friendly Dynamic CLI for Developers

Javier Leandro Arancibia — Sat, 25 Apr 2026 06:59:32 +0000

Introducing SuperCLI: A Config-Driven, AI-Friendly Dynamic CLI for Developers

As developers, we constantly juggle dozens of CLI tools — from essential utilities like git and docker to specialized tools for testing, linting, and deployment. Managing this tool ecosystem is challenging: different interfaces, inconsistent flags, and the constant need to learn new commands.

SuperCLI (also known as superacli or sc) is a config-driven, AI-friendly dynamic CLI that unifies your development tools under a single, consistent interface.

What is SuperCLI?

SuperCLI is a wrapper that lets you define tools through JSON configuration files. Instead of memorizing each tool's specific flags and syntax, you interact with everything through a unified command structure:

sc <namespace> <resource> <action> [flags]

For example:

# Check git version
sc git self version

# List Docker containers
sc docker container list

# Run tests with jest
sc jest test run --watch

Key Features

1. Config-Driven Architecture

Tools are defined in plugin.json files that specify:

Commands and their arguments
Input validation schemas
Help text and descriptions
Installation checks

This means:

No need to memorize tool-specific syntax
Consistent interface across all tools
Easy to add new tools
Self-documenting commands

2. AI-Friendly Design

SuperCLI was built with AI agents in mind:

Structured JSON schemas for command inputs
Clear descriptions for each parameter
Consistent naming conventions
Skill files that teach agents how to use each tool

AI agents can discover available commands, understand their parameters, and execute them reliably without manual intervention.

3. Bundled Plugin Ecosystem

SuperCLI comes with 350+ pre-configured plugins covering:

Development tools: git, docker, npm, cargo, brew
Testing: jest, pytest, go test
Code quality: eslint, prettier, black
File operations: ripgrep, fd, tokei
Network tools: curl, wget, httpie
And many more: 350+ plugins across all categories

4. Extensible Plugin System

Add your own tools by creating a simple JSON configuration:

{
  "name": "my-tool",
  "version": "0.1.0",
  "description": "My custom tool",
  "commands": [
    {
      "namespace": "my-tool",
      "resource": "build",
      "action": "run",
      "adapter": "process",
      "adapterConfig": {
        "command": "my-tool",
        "baseArgs": ["build"]
      }
    }
  ]
}

5. Multiple Adapters

SuperCLI supports different execution backends:

Process adapter: Execute CLI commands
HTTP adapter: Make HTTP requests
MCP adapter: Connect to Model Context Protocol servers
Builtin adapter: Built-in commands

6. Server Mode

Run SuperCLI as a web server for:

Remote tool execution
Team configuration sharing
API-based tool access
Dashboard UI for plugin management

Getting Started

Installation

npm install -g superacli

Or use any of the aliased commands:

npm install -g dcli
npm install -g scli
npm install -g supercli
npm install -g sc

Basic Usage

# List all available commands
sc list

# Get help for a specific command
sc git self --help

# Execute a command
sc git branch list

Adding Plugins

# Install a bundled plugin
sc plugins install ./plugins/ripgrep --on-conflict replace

# List installed plugins
sc plugins list

# Remove a plugin
sc plugins remove ripgrep

Use Cases

For Individual Developers

Unified interface: One command syntax for all tools
Reduced cognitive load: No need to remember tool-specific flags
Quick discovery: sc list shows all available commands
Easy learning: Consistent patterns across tools

For Teams

Shared configuration: Distribute plugin configurations
Standardized workflows: Enforce consistent tool usage
Server mode: Centralized tool access
Documentation: Self-documenting command structure

For AI Agents

Structured inputs: JSON schemas for reliable execution
Clear semantics: Namespace/resource/action structure
Skill files: Teachable patterns for each tool
Discoverable: Agents can query available commands

Real-World Examples

Code Analysis Workflow

# Count lines of code
sc tokei self stats

# Search for TODO comments
sc rg search --pattern "TODO" --type-add "md:*.md" --type md

# Format code
sc prettier format --write "src/**/*.ts"

# Run linter
sc eslint lint --fix "src/**/*.ts"

Deployment Pipeline

# Build Docker image
sc docker image build --tag myapp:latest

# Run tests
sc jest test run --coverage

# Deploy to production
sc kubectl deployment apply --file k8s/deployment.yaml

Project Setup

# Initialize git repository
sc git repo init

# Install dependencies
sc npm install

# Run initial build
sc npm run build

# Run tests
sc jest test run

Advanced Features

MCP Integration

SuperCLI supports the Model Context Protocol (MCP), enabling stateful tool sessions and knowledge base integration:

# Start MCP daemon
sc mcp daemon start

# Call MCP tools
sc mcp call --mcp-server context-mode --tool ctx_search --input-json '{"queries":["routes"]}'

Environment Variable Management

# Set environment variables
sc config set ENV production

# Get environment variables
sc config get ENV

Custom Aliases

Create shortcuts for frequently used commands:

sc alias create "build" "npm run build"
sc alias create "test" "jest test run"

Architecture

SuperCLI follows a clean, modular architecture:

┌─────────────────────────────────────┐
│         CLI Interface              │
│    (sc, supercli, dcli, scli)       │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      Command Router                 │
│   Parse namespace/resource/action    │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      Plugin Registry                │
│   Load and manage plugin configs    │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      Adapter Layer                  │
│  Process | HTTP | MCP | Builtin      │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      Tool Execution                 │
│   Execute commands via adapters     │
└─────────────────────────────────────┘

Contributing

SuperCLI is open source and welcomes contributions:

Add new plugins: Create plugin configurations for your favorite tools
Improve adapters: Enhance existing adapters or add new ones
Fix bugs: Report and fix issues
Documentation: Improve docs and examples

GitHub: https://github.com/javimosch/supercli

Roadmap

[ ] More bundled plugins (target: 500+)
[ ] Enhanced MCP integration
[ ] Plugin marketplace
[ ] Web UI improvements
[ ] Performance optimizations
[ ] Better error messages

Conclusion

SuperCLI provides a unified, AI-friendly interface for your development tools. By standardizing command structures and providing a rich plugin ecosystem, it reduces cognitive load and enables both humans and AI agents to work more efficiently.

Whether you're an individual developer looking to simplify your CLI workflow, a team wanting to standardize tool usage, or an AI agent seeking reliable tool execution, SuperCLI offers a flexible and powerful solution.

Get started today:

npm install -g superacli
sc list

Links:

GitHub: https://github.com/javimosch/supercli
NPM: https://www.npmjs.com/package/superacli
Documentation: https://github.com/javimosch/supercli/blob/master/README.md

New Dev.to Publish Plugin for SuperCLI: Publish Articles from the Command Line

Javier Leandro Arancibia — Sat, 25 Apr 2026 06:06:10 +0000

I just released a new plugin for supercli that lets you publish articles to Dev.to directly from the command line.

What is devto-publish?

devto-publish is a supercli plugin that wraps the Dev.to REST API, allowing you to publish articles without leaving your terminal.

Usage

sc devto article publish   --api-key "your-api-key"   --title "My Article Title"   --body-markdown "# Content here"   --tags "javascript,nodejs"

Features

Draft mode: Save as drafts before publishing
Tag management: Up to 4 tags with comma-separated format
Agent-friendly: Comprehensive skill guide with 10 common pitfalls
API key authentication: Secure flag-based auth

Setup

Get API key from https://dev.to/settings/account
Install plugin: sc plugins install ./plugins/devto-publish
Publish away!

Agent Integration

The plugin includes a detailed SKILL.md that teaches AI agents how to use it, covering:

API key security best practices
Markdown escaping pitfalls
Tag format requirements
Rate limiting handling
Character encoding issues

This means agents using supercli can now publish articles to Dev.to as part of their workflows.

Example

Publish a technical article:

sc devto article publish   --api-key "$DEVTO_API_KEY"   --title "How to Build a REST API with Node.js"   --body-markdown "$(cat article.md)"   --tags "javascript,nodejs,api,webdev"

How We Made Stateful MCP Servers Work in One-Shot CLI Calls

Javier Leandro Arancibia — Sat, 25 Apr 2026 05:54:43 +0000

How We Made Stateful MCP Servers Work in One-Shot CLI Calls

The Problem: Stateful Servers vs Stateless CLI

Context-mode is a powerful MCP (Model Context Protocol) server that maintains a SQLite knowledge base and session history. It reduces AI context window usage by up to 98% by keeping raw tool output out of conversations and only returning relevant snippets.

But there was a problem: context-mode is stateful. It needs to stay alive between calls to maintain its knowledge base. Traditional CLI tools are stateless — each invocation is a fresh process.

When we tried to integrate context-mode into supercli (a CLI wrapper for external tools), we hit a wall:

# Call 1: Index project structure
sc mcp call --mcp-server context-mode --tool ctx_index --input-json '{"content":"..."}'

# Call 2: Search — but knowledge is gone! New process, new database.
sc mcp call --mcp-server context-mode --tool ctx_search --input-json '{"queries":["routes"]}'

Each sc call spawned a new context-mode process. The knowledge base was lost between calls. Agents using supercli in one-shot CLI invocations couldn't benefit from context-mode's stateful features.

The Solution: MCP Daemon

We built a daemon process manager that keeps MCP servers alive persistently across CLI invocations.

Architecture

┌─────────────────────────────────────────────────────────┐
│  CLI Call (one-shot)                                     │
│  sc mcp call --mcp-server context-mode --tool ctx_search │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  MCP Daemon (persistent background process)             │
│  Unix socket: ~/.supercli/mcp-daemon.sock               │
│  Process pool: Map<<serverName, ChildProcess>>           │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  context-mode (long-lived process)                      │
│  SQLite knowledge base persists across CLI calls        │
└─────────────────────────────────────────────────────────┘

Key Features

Unix Socket Server: Daemon listens on ~/.supercli/mcp-daemon.sock for JSON-RPC requests
Process Pool: Maintains long-lived child processes for each MCP server
Auto-Start: Daemon starts automatically on first tool call if not running
Stateful Flag: MCP servers can be marked as stateful: true to use the daemon
Graceful Shutdown: Cleanly stops all MCP processes on daemon exit

Implementation

Daemon (cli/mcp-daemon.js):

// Unix socket server
const server = net.createServer((socket) => {
  socket.on('data', (chunk) => {
    const req = JSON.parse(chunk);
    if (req.method === 'call_tool') {
      const entry = await getOrSpawnServer(req.params.server, req.params.serverConfig);
      const result = await callTool(entry, req.params.tool, req.params.input);
      socket.write(JSON.stringify({ id: req.id, result }) + '\n');
    }
  });
});
server.listen(SOCKET_PATH);

Client (cli/mcp-daemon-client.js):

async function callDaemonTool({ server, serverConfig, tool, input, timeout_ms }) {
  if (!await isDaemonRunning()) {
    await startDaemon(); // Auto-start if not running
  }
  return sendDaemonRequest('call_tool', { server, serverConfig, tool, input, timeout_ms });
}

MCP Adapter (cli/adapters/mcp.js):

if (config.stateful) {
  // Route through daemon instead of spawning new process
  return callDaemonTool({ server, serverConfig, tool, input, timeout_ms });
} else {
  // Existing behavior: spawn per call
  return stdioCallToolJsonRpc({ ... });
}

Usage

Installation

npm install -g context-mode
sc plugins install ./plugins/context-mode --on-conflict replace --json
# Automatically registers as stateful MCP server + starts daemon

CLI Commands

# Daemon management
sc mcp daemon start     # Start daemon
sc mcp daemon status    # Check status + active servers
sc mcp daemon stop      # Stop daemon
sc mcp daemon restart   # Restart daemon

# Add stateful MCP server
sc mcp add my-server --command my-tool --stateful

# Call context-mode tools (knowledge persists across calls)
sc mcp call --mcp-server context-mode --tool ctx_batch_execute --input-json '{
  "commands": [
    {"label": "Package", "command": "cat package.json"},
    {"label": "Source tree", "command": "find src -name \"*.js\" | head -40"}
  ],
  "queries": ["entry point", "dependencies"]
}'

Benefits

1. Knowledge Base Persistence

# Call 1: Index docs
sc mcp call --mcp-server context-mode --tool ctx_index --input-json '{
  "content": "...large documentation...",
  "source": "api-docs"
}'

# Call 2 (new shell, new process): Knowledge persists!
sc mcp call --mcp-server context-mode --tool ctx_search --input-json '{
  "queries": ["authentication", "token expiry"]
}'

2. Context Window Reduction

ctx_batch_execute runs commands, auto-indexes output, and searches in one call — returning only matched snippets, not raw output:

Executed 3 commands (57 lines, 1.4KB). Indexed 3 sections. Searched 4 queries.

## dependencies (only relevant snippets returned)

### Package
{
  "dependencies": {
    "dotenv": "^17.3.1",
    "ejs": "^3.1.9",
    "express": "^4.18.2",
    "mongodb": "^6.3.0"
  }
}

3. Agent-Friendly

Agents call supercli as one-shot commands. The daemon ensures knowledge base persistence:

# Agent call 1
sc mcp call --mcp-server context-mode --tool ctx_batch_execute ...

# Agent call 2 (different process, different shell)
sc mcp call --mcp-server context-mode --tool ctx_search ...
# Knowledge base still available via daemon

4. Zero Setup for Agents

The daemon auto-starts on first tool call. Agents don't need to manage it:

# First call: daemon auto-starts
sc mcp call --mcp-server context-mode --tool ctx_doctor --input-json '{}'

# Subsequent calls: daemon already running
sc mcp call --mcp-server context-mode --tool ctx_search ...

Technical Details

Protocol

Daemon uses JSON over Unix socket:

// Request
{"id": 1, "method": "call_tool", "params": {"server": "context-mode", "tool": "ctx_search", "input": {...}}}

// Response
{"id": 1, "result": {...}}

Process Lifecycle

Daemon starts (detached process, no TTY)
First tool call → daemon spawns context-mode process
JSON-RPC handshake (initialize → notifications/initialized)
Tool calls routed through daemon
Process stays alive for subsequent calls
Daemon shutdown → graceful termination of all MCP processes

Wire Mode

We discovered context-mode uses JSONL (newline-delimited JSON) not LSP framing. The daemon defaults to JSONL for stdio MCP servers:

const entry = {
  wireMode: serverConfig.wire_mode || "jsonl", // Default to JSONL
  ...
};

Future Directions

Now that we have the daemon infrastructure, we can explore:

Automatic output reduction: Process adapter could pipe output through context-mode automatically
Ask command caching: LLM suggestions cached in knowledge base
Workflow context: Cross-step knowledge indexing
Error learning: Pattern-based error solutions
Server mode shared KB: Collective intelligence across API clients

Conclusion

The MCP daemon enables stateful MCP servers like context-mode to work seamlessly in one-shot CLI environments. Agents get full context-mode benefits (98% context reduction, knowledge base persistence) while supercli remains a clean, stateless CLI wrapper.

The architecture is extensible — any stateful MCP server can now integrate with supercli via the daemon, opening possibilities for persistent tool sessions across CLI invocations.

Try it out:

npm install -g context-mode
sc plugins install ./plugins/context-mode --on-conflict replace --json
sc mcp daemon status
sc mcp call --mcp-server context-mode --tool ctx_doctor --input-json '{}'