@agent-smith/cli — Terminal REPL for Agent Smith

A command-line interface built with Commander.js for interacting with AI agents, executing workflows and actions, managing configuration, and running inference. Part of the Agent Smith toolkit.

Features

• 🚀 Interactive REPL — Chat mode for conversational agent interaction
• ⚡ One-shot Commands — Run agents, workflows, and actions from the terminal
• 🔧 Dynamic Commands — Auto-generated commands from database features (agents, actions, workflows, aliases)
• 🎛️ Configuration Management — YAML-based config with SQLite backend for backends, plugins, and feature paths
• 🌐 Multi-Backend Support — Llama.cpp, Koboldcpp, Ollama, OpenRouter, and any OpenAI-compatible API
• 📋 I/O Flexibility — Clipboard input/output, file input, markdown output modes
• 🔍 Inference Control — Fine-grained control over model parameters (temperature, top_k, top_p, min_p, etc.)
• 🔄 Hot-Reloadable Features — Add agents and tools without restarting the CLI

Documentation

For AI Agents

• Codebase Summary — Architecture, key files, and patterns for the CLI package
• Overview — Terminal client principles and feature types
• Install — Installation and quickstart
• Config — Configuration file format and backend setup
• Agents — Agent YAML definitions and tool calling
• Tasks — Running agents with variables and parameters
• Actions — Custom tool scripts (JS, Python, YAML)
• Workflows — Chaining actions and agents in pipelines
• Commands — Custom terminal commands

For Humans

• Quickstart Guide — Get up and running in minutes
• Terminal Client Overview — Principles and feature types
• Installation — Install and initial configuration
• Configuration — Config file format, backends, and plugins
• Agent Definitions — Declaring agents with YAML
• Tasks & Variables — Parameterized agent execution
• Actions — Writing custom tools
• Workflows — Building multi-step pipelines

Installation

npm i -g @agent-smith/cli

This installs the lm command globally.

Quick Start

1. Initialize a config file

Run lm conf to initialize. A basic config file will be created (~/.config/agent-smith/config.yml on Linux):

backends:
  default: llamacpp
  llamacpp:
    url: http://localhost:8080/v1

2. Configure your backend

Customize your config:

backends:
  default: "llamacpp"
  llamacpp:
    url: "http://localhost:8080/v1"
  openrouter:
    type: "openai"
    url: "https://openrouter.ai/api/v1"
    apiKey: "$OPENROUTER_API_KEY" # env variable

Run lm conf again to synchronize. This processes the YAML config and populates the SQLite database (at ~/.config/agent-smith/config.db on Linux).

3. Run a Quick Query

lm q list the planets of the solar system

With a specific model:

lm q list the planets of the solar system -m gemma4b

4. Enter Interactive Chat Mode

lm

Then type your queries interactively. Use exit to quit.

Usage

Listing Agents

List all registered agents:

lm agents

View an agent definition:

lm agent myagent

Running Agents

Run a specific agent with a prompt:

lm myagent "Explain quantum computing"

With variables (if the agent requires them):

lm myagent "Analyze this code" --workspace /path/to/project

Using Different Backends

Change the default backend:

lm backend openrouter

Use a specific backend for one execution:

lm myagent "Hello" -b llamacpp

List available backends:

lm backends

Inference Parameters

Control model behavior with command-line options:

lm q "Write a poem" \
  --model qwen4b \
  --temperature 0.7 \
  --top_k 20 \
  --top_p 0.95 \
  --max_tokens 1024

Input/Output Modes

Clipboard input:

lm q "Summarize this" --ic

File input:

lm q "Analyze" --if

Markdown output:

lm q "Generate a report" --markdown-output

Clipboard output:

lm q "Generate code" --oc

Chat Mode for Tasks

Enable chat mode for multi-turn task execution:

lm myagent "Start a project" -c

Verbose and Debug Modes

lm q "Hello" --verbose    # Show detailed execution info
lm q "Hello" --debug       # Show debug-level output

Complete Example

Here's a full workflow: configuring backends, creating an agent, and running it with custom parameters.

Step 1: Create Features Directory

mkdir -p ~/my-agents/features/agents
mkdir -p ~/my-agents/features/actions

Step 2: Configure Features Path

Update ~/.config/agent-smith/config.yml:

features:
  - ~/my-agents/features
backends:
  default: "llamacpp"
  llamacpp:
    type: "openai"
    url: "http://localhost:8080/v1"

Run lm conf to synchronize the conf db

Step 3: Create an Agent

Create ~/my-agents/features/agents/shell-demo.yml:

description: A demo agent
prompt: |-
  Custom prompt here.
  User input: {prompt}
template:
  system: |-
    Custom system prompt here
model: qwen4b
inferParams:
  min_p: 0
  top_k: 20
  top_p: 0.95
  temperature: 0.4

Step 4: Register and Run

# Register the new agent
lm update

# Run with a prompt and variable
lm demo "user prompt here" -v # -v is to see thinking tokens

API Reference

CLI Entry Point

The package exports utility functions for integration:

import {
    displayOptions,
    ioOptions,
    inferenceOptions,
    allOptions,
    parseCommandArgs
} from "@agent-smith/cli";

Options

| Export | Type | Description | |--------|------|-------------| | displayOptions | Option[] | CLI display options (--verbose, --debug) | | ioOptions | Option[] | I/O mode options (clipboard, file, markdown) | | inferenceOptions | Option[] | Inference parameter options (model, temperature, etc.) | | allOptions | Option[] | Combined options array | | parseCommandArgs | Function | Parse command-line arguments for Commander.js |

Inference Options

| Option | Short | Description | |--------|-------|-------------| | --model <name> | -m | Model name to use | | --ctx | -x | Context window size | | --template <template> | --tpl | Template to use | | --max_tokens <number> | --mt | Maximum tokens to generate | | --top_k <number> | -k | Limit results to top K | | --top_p <number> | -p | Cumulative probability filter | | --min_p <number> | --mp | Minimum token probability | | --temperature <number> | -t | Sampling randomness | | --repeat_penalty <number> | -r | Penalty for repeated tokens | | --backend <name> | -b | Backend to use (must be registered) | | --mcp [args...] | — | MCP server arguments |

I/O Options

| Option | Short | Description | |--------|-------|-------------| | --input-file | --if | Use promptfile input mode | | --clipboard-input | --ic | Use clipboard input mode | | --manual-input | --im | Manual input (default) | | --clipboard-output | --oc | Output to clipboard | | --markdown-output | --omd | Markdown output format | | --text-output | --otxt | Text output (default) |

Important Notes

• Node.js Required: This package runs in Node.js environments only — it is not a browser library.
• Global Installation: Designed for global installation via npm i -g. The lm binary is available system-wide.
• SQLite Database: Configuration and features are stored in SQLite at ~/.config/agent-smith/config.db.
• Dependencies: Requires @agent-smith/core for feature execution and database operations.
• Backend Compatibility: Supports any server with an OpenAI-compatible API (Llama.cpp, Ollama, Koboldcpp, OpenRouter, etc.).
• Related Packages:
  • @agent-smith/core — Runtime engine for feature execution
  • @agent-smith/agent — Agent inference loop
  • @agent-smith/wscli — WebSocket client for server communication

License

MIT