Command-Line Interface (CLI)
Relevant source files
The following files were used as context for generating this wiki page:
The Loom Command-Line Interface (CLI) is a comprehensive suite of tools for managing the entire lifecycle of Loom projects. It serves as the primary interface for developers to handle runtime management, orchestrate multi-agent systems, interact with cognitive agents, and perform development tasks like project scaffolding and benchmarking. The CLI is designed to streamline both development and deployment workflows.
The CLI is powered by the loom.runtime module, which handles the orchestration of the Rust Core, Bridge, Dashboard, and Python agent processes. This separation allows the CLI to provide a simple, high-level command set while relying on a robust backend for execution.
Sources: loom-py/src/loom/cli/README.md, loom-py/src/loom/runtime/README.md
Core Commands
The CLI provides several commands to manage different aspects of a Loom project.
| Command | Description | Use Case |
|---|---|---|
loom up | Starts the Loom runtime (Core, Bridge, Dashboard). | Development, production deployment. |
loom down | Stops all Loom-related processes gracefully. | Cleanup, restarting the environment. |
loom run | Runs a Loom project, including the runtime and agents. | Multi-agent orchestration. |
loom chat | Starts an interactive terminal chat with a cognitive agent. | Testing, debugging, and demos. |
loom benchmark | Runs industry-standard benchmarks against agents. | Performance and quality evaluation. |
loom init | Creates a new Loom project from a template. | Project scaffolding. |
loom proto | Generates Python gRPC stubs from .proto files. | Development workflow for gRPC changes. |
loom dev | Starts the gRPC Bridge from local Rust source code. | Core Rust development. |
Sources: loom-py/src/loom/cli/README.md:13-22
loom up - Runtime Management
The loom up command is responsible for starting the Loom runtime. It automatically handles the download and caching of pre-built binaries for the Rust Core, Bridge, and Dashboard.
This diagram illustrates the process flow for the loom up command.
Options:
| Option | Description | Default |
|---|---|---|
--mode | Runtime mode (full or bridge-only). | full |
--version | Runtime version to use. | latest |
--bridge-port | The gRPC port for the Bridge. | 50051 |
--dashboard-port | The HTTP port for the Dashboard. | 3030 |
--use-debug | Prefer debug builds over release builds. | false |
--force-download | Force download from GitHub, skipping any cache. | false |
Binary Selection Priority:
The command follows a specific order to find the required binaries:
- Local builds in
target/release/ortarget/debug/. - Cached binaries in
~/.cache/loom/bin/. - GitHub releases (downloaded and cached automatically).
Sources: loom-py/src/loom/cli/README.md:32-58, loom-py/README.md:28-48
loom down - Stop Runtime
This command gracefully stops all running Loom processes, including the runtime components and any managed agent processes. It first sends a SIGTERM signal for a graceful shutdown and, after a 3-second timeout, sends a SIGKILL to force-terminate any remaining processes.
Sources: loom-py/src/loom/cli/README.md:62-72, loom-py/README.md:45-51
loom run - Project Orchestration
The loom run command starts a full project, including the runtime and all associated agents. It features an auto-discovery mechanism that finds agents in agents/*.py, entry points like main.py, or as defined in loom.toml.
This diagram shows the orchestration flow for the loom run command.
Options:
| Option | Description | Default |
|---|---|---|
| `[SCRIPT | DIR]` | Optional script or directory to run. |
--logs | Enable log file creation in a logs/ directory. | false |
Sources: loom-py/src/loom/cli/README.md:76-102, apps/market-analyst/README.md:40-47
Interactive Chat (loom chat)
The loom chat command provides an interactive terminal-based interface for communicating with a CognitiveAgent. It showcases the agent's reasoning process, including thoughts, tool calls, and final answers, using a rich UI powered by the rich library.
Architecture and Flow
When a user starts a chat, the CLI initiates a CognitiveAgent. This agent follows a perceive-think-act loop, using an LLMProvider to reason and a ToolExecutor to interact with its environment.
This sequence diagram shows the interaction flow during a loom chat session.
User Interface and Display
The chat interface is built using components from loom.cli.ui, which provides a consistent and visually appealing terminal experience.
- Streaming Display: The
ReactStreamRendererorSimpleStreamRendererclasses are used to display the agent's thought process in real-time. This includes thoughts, tool calls, and observations. - Rich Formatting:
richis used for syntax highlighting, panels, tables, and styled text to differentiate between user input, agent thoughts, tool actions, and final answers. - Interactive Commands: The chat session supports slash commands for managing the conversation.
Interactive Commands:
| Command | Description |
|---|---|
/clear | Clear conversation history. |
/stats | Show session statistics. |
/history | Show conversation history. |
/verbose | Toggle verbose mode (show thinking steps). |
/stream | Toggle streaming mode. |
/exit or /quit | Exit the chat session. |
Sources: loom-py/src/loom/cli/ui.py, loom-py/src/loom/cli/README.md:121-125
Benchmarking (loom benchmark)
The loom benchmark command group provides a powerful framework for evaluating agent performance against industry-standard benchmarks like SWE-bench.
Subcommands
run: Executes a benchmark against an agent, collecting metrics on performance, token usage, and cost.compare: Runs a comparison between two configurations (e.g., with and without context engineering) to measure the impact of optimizations.report: Generates a human-readable report in the console or as a Markdown file from benchmark result files.
This flowchart shows a typical workflow for using the benchmark commands.
Other Commands
loom init
Initializes a new Loom project directory with a template agent.py and a loom.toml configuration file, providing a quick start for new development.
Sources: loom-py/src/loom/cli/README.md:129-140
loom proto
Generates Python gRPC stubs from the .proto files. This is a developer utility used when modifying the gRPC service definitions between the Rust Core and Python SDK.
Sources: loom-py/src/loom/cli/README.md:144-153
loom dev
Starts the Loom Bridge server directly from local Rust source code. This command is intended for developers working on the Rust components of Loom, allowing for rapid iteration without needing to use pre-built binaries.
Sources: loom-py/src/loom/cli/README.md:157-168
Environment Variables
The CLI's behavior can be modified using several environment variables.
| Variable | Description |
|---|---|
LOOM_BRIDGE_ADDR | Overrides the default gRPC Bridge address (e.g., localhost:50051). |
DEEPSEEK_API_KEY | API key for the DeepSeek LLM provider. |
OPENAI_API_KEY | API key for the OpenAI LLM provider. |
OTEL_SERVICE_NAME | Sets the service name for OpenTelemetry tracing. |
OTEL_EXPORTER_OTLP_ENDPOINT | Specifies the OTLP endpoint for telemetry data. |