Aclif: The Unified Agent CLI Framework

Aclif is a specialized framework designed to construct command-line interfaces specifically for AI agents. Rather than forcing an agent to learn a dozen different APIs, Aclif provides a single, unified abstraction across all SaaS providers. This means one consistent grammar and canonical names that ensure the same record is accessed by the same name, regardless of the underlying platform.

🚀 Quick Start

You can begin exploring Aclif by installing the binary and utilizing the discovery and learning commands:

# Install the core framework
npm install -g @aclif/core

# Explore available providers
aclif discover --json

# Learn about specific platform capabilities
aclif learn salesforce --json
aclif learn servicenow --json

# Introspect a specific command
aclif salesforce data query --schema
aclif salesforce data query --examples

# Execute with a safety check
aclif salesforce data query --query "SELECT Id FROM Account LIMIT 3" --dry-run
aclif servicenow data query --table incident --query "active=true^priority=1" --dry-run

---

🧠 Why Agents Need a Dedicated CLI

Traditional MCP (Model Context Protocol) servers publish a static list of tools. This creates a significant trade-off for the developer:

The Coverage vs. Cost Dilemma: If a server publishes every single API operation (which can number in the hundreds), the agent's context window is flooded, consuming massive amounts of tokens on every single turn. Conversely, if the author only publishes a few broad tools to save tokens, the agent loses access to the full power of the API.

Aclif solves this by loading command definitions on-demand.

Context Efficiency

In a standard MCP setup, the token cost $C$ is: $C = \sum_{i=1}^{n} \text{ToolDefinition}_i$ With Aclif, the cost is reduced to: $C \approx \text{ActiveCommandDefinition}$

By utilizing one grammar, one envelope, and one error vocabulary, the agent's context remains stable whether it is interacting with one SaaS platform or five.

Workflow Optimization

For predefined workflows, the LLM can be bypassed entirely. A developer can embed a specific command string into a workflow at design time. At runtime, the agent executes this string as standard code—no inference required—meaning no tool definitions are loaded and no tokens are spent on decision-making.

---

🛠️ Core Capabilities

1. Unified Grammar & Canonicalization

Aclif ensures that adding a new platform doesn't mean learning a new language.

2. Advanced Introspection

Agents can "study" a command before executing it. Using flags like --schema, --examples, and --shape, an agent can:

• Discover capabilities.
• Learn syntax.
• Preview responses.
• All without consuming API quotas or requiring active credentials.

3. Declared Safety

Every command includes explicit metadata regarding its impact:

• Mutability: Is it a read or write operation?
• Blast Radius: How much data is affected?
• Reversibility & Idempotency: Can it be undone or repeated safely?

Safety Mechanisms:

• --dry-run: Validates the command without executing changes.
• --confirm: Mandatory prompt for high-risk mutations.
• Audit Logging: Every execution writes a permanent audit line.

---

🏗️ Architecture & Runtime

Aclif's command classes are embeddable, allowing them to run in-process within a host that manages identity and policy.

Three Deployment Models

1. Direct Binary: The agent spawns the binary and reads the JSON output. Credentials are provided via environment variables or flags. Best for: Single operator/agent trust boundaries.
2. Application-Mediated: An app sits between the model and Aclif. The model calls a tool, and the app executes the Aclif command. Best for: Keeping credentials away from the LLM and reducing context load.
3. Deployed Gateway: A long-lived process serves as a centralized hub, integrating with enterprise identity providers and secrets vaults to maintain warm connections and cached logins.

🔄 The Introspection-First Workflow

The agent follows a logical path from discovery to execution:

1. aclif discover --json $\rightarrow$ Identify available providers.
2. aclif learn [provider] --json $\rightarrow$ Understand topics and auth paths.
3. aclif [provider] [cmd] --schema $\rightarrow$ Check flags and safety metadata.
4. aclif [provider] [cmd] --examples $\rightarrow$ See expected input/output.
5. aclif [provider] [cmd] --dry-run $\rightarrow$ Validate the specific query.
6. aclif [provider] [cmd] --json $\rightarrow$ Final execution.

The resulting JSON envelope includes a _context block, providing pagination details, available fields, and suggestions for the next logical command.