Stop Teaching LLMs to Use APIs: Unpacking clawrise-cli

How a Go-based CLI uses JSON-RPC over standard I/O to give autonomous agents a stable, multi-account grip on enterprise SaaS.

7 min read • View on GitHub • More from repothread

A complex, fragile cluster of glass gears representing a web API cracking under the pressure of a mechanical robot hand, contrasted with a solid steel industrial lever. — Raw APIs require LLMs to manage fragile HTTP state. clawrise-cli provides a sturdy, machine-readable abstraction layer.

Key Takeaways

clawrise-cli acts as a machine-to-machine operating system, giving AI agents a standardized, strictly typed CLI to interact with enterprise SaaS.
It uses a custom JSON-RPC protocol over standard input and output to manage decoupled plugins, eliminating network overhead.
Authentication is decoupled from execution, allowing agents to perform tasks across multiple accounts without ever touching raw bearer tokens.
Instead of relying on human-readable documentation, clawrise-cli provides YAML playbooks that act as deterministic training data for LLMs.

The Hallucination at the API Layer

Feeding raw REST API documentation to a Large Language Model is a recipe for disaster. While Claude and Codex excel at writing isolated functions, they struggle with the realities of modern web APIs. They hallucinate nested JSON structures, forget idempotency keys, and completely fail at multi-step OAuth flows.

Even when prompt engineering yields a correct request, network timeouts and rate limits introduce state management complexities that LLMs are ill-equipped to handle. clawrise-cli introduces a rigid, machine-centric middle layer: a command-line interface built explicitly for agent execution, not human fingers.

JSON-RPC over Stdio: The Machine-to-Machine CLI

Go’s native plugin package is notoriously difficult to use, often plagued by versioning conflicts and CGO requirements. clawrise-cli bypasses this entirely.

Instead, the main CLI binary spawns separate plugin binaries—like clawrise-plugin-notion—and communicates with them using JSON lines over standard input and output (Stdio). This creates a zero-network-overhead microservice architecture inside the terminal.

The Stdio RPC Pipeline: Decoupled microservices within the terminal without network overhead.

Decoupled Auth and Execution Identity

Security is paramount when giving autonomous agents access to enterprise systems. clawrise addresses this by separating token acquisition from execution via decoupled auth launchers.

A close-up of a massive steel bank vault door with a single mail-slot. A mechanical pincer is sliding a rigid metal envelope through the slot, while the vault's internal locking mechanisms are sealed off. — The ExecuteIdentity pattern ensures the AI only passes the request envelope, never touching the internal credentials.

The ExecuteIdentity struct is central to this design. The AI never sees an OAuth token; it simply passes an account identity, and the CLI handles the secure execution.

type ExecuteIdentity struct {
    Platform    string      `json:"platform"`
    Subject     string      `json:"subject"`
    AccountName string      `json:"account_name"`
    Auth        ExecuteAuth `json:"auth"`
}

Playbooks as Machine Documentation

Traditional CLIs rely on -h flags and human intuition. clawrise shifts this paradigm by shipping with structured YAML 'playbooks' in its docs/playbooks/ directory.

These playbooks act as deterministic training data, teaching the LLM exactly which commands to string together for complex workflows, optimizing for token efficiency and preventing hallucinated commands.

Bridging the Enterprise Divide

The framework utilizes an adapter pattern to support both Western-centric platforms like Notion and Asian-centric platforms like Feishu/Lark. This positions clawrise-cli as a universal translator for global organizations running disparate tech stacks.

Feature	Raw APIs	Clawrise-CLI
Authentication	Requires multi-step OAuth or exposing raw bearer tokens to the LLM context.	Uses decoupled Auth Launchers; agents only pass a string <code>account_name</code>.
Resiliency	Leaves retry logic and idempotency up to the LLM's prompt.	Enforces an <code>IdempotencyKey</code> at the CLI layer to prevent duplicate actions.
Communication	Requires the LLM to write exact JSON structures over HTTP.	Uses local Stdio JSON-RPC, eliminating network timeout hallucinations.
Context Discovery	Forces the LLM to read massive HTML/Markdown docs.	Provides YAML playbooks optimized for token efficiency.