CLI Overview

Complete guide to the Loom CLI - an AI-powered coding agent with interactive REPL

What is Loom CLI?

Loom is an interactive AI-powered coding assistant that provides a REPL (Read-Eval-Print Loop) interface for natural language conversations with LLM agents. The agent has access to powerful tools for reading, editing, and executing code in your workspace.

Installation

# Build from source
cd crates/loom-cli
cargo build --release

# Or use Nix (preferred for reproducible builds)
nix build .#loom-cli-c2n

Quick Start

# Authenticate with Loom server
loom --server-url https://loom.ghuntley.com login

# Start a new interactive session
loom

# Start a private (local-only) session
loom private

# Resume the most recent session
loom resume

Core Commands

login

Authenticate with Loom services using device code flow

logout

Log out and clear credentials

resume

Resume an existing conversation thread

private

Start a local-only session that never syncs

Global Flags

--config · string

Path to custom configuration file

--workspace · string

Workspace directory for file operations (defaults to current directory)

--log-level · string

Log level: trace, debug, info, warn, error (overrides config)

--json-logs · boolean

Output logs as JSON (overrides config)

--server-url · string · default: "http://localhost:8080"

Loom server URL for LLM proxy

Can also be set via LOOM_SERVER_URL environment variable

--provider · string · default: "anthropic"

LLM provider to use: anthropic or openai

Can also be set via LOOM_LLM_PROVIDER environment variable

Authentication

Device Code Flow

Loom uses OAuth2 device code flow for authentication:

loom --server-url https://loom.ghuntley.com login

This will:

1. Generate a device code and user code
2. Open your browser to the verification URL
3. Display the user code to enter
4. Poll the server until you complete authorization
5. Store the access token securely in your system keyring (with file fallback)

Credentials Storage

Credentials are stored using loom-cli-credentials with:

• Primary: System keyring (secure OS credential store)
• Fallback: ~/.config/loom/credentials.json (if keyring unavailable)

Logout

loom --server-url https://loom.ghuntley.com logout

This clears stored credentials and notifies the server to invalidate the token.

Thread Management

List Threads

loom list

Output:

ID                                       TITLE                           MSGS  LAST ACTIVITY
----------------------------------------------------------------------------------------------------
01HX2K3M4N5P6Q7R8S9T0V1W2X3Y4Z5A6B7C8D9E  Fix authentication bug             12  2024-03-15 14:23:11
01HX2K3M4N5P6Q7R8S9T0V1W2X3Y4Z5A6B7C8D9F  Add new API endpoint                8  2024-03-15 10:15:42

Resume Thread

# Resume most recent thread
loom resume

# Resume specific thread by ID
loom resume 01HX2K3M4N5P6Q7R8S9T0V1W2X3Y4Z5A6B7C8D9E

Private Sessions

Private sessions are local-only and never sync to the server:

loom private

Use this for:

• Working with sensitive code
• Testing without server connectivity
• Offline development

Search Threads

# Search by text, branch name, repo URL, or commit SHA
loom search "authentication"

# Limit results
loom search "api" --limit 10

# JSON output
loom search "bug fix" --json

Sharing Threads

Change Visibility

# Share with organization
loom share --visibility organization

# Make private
loom share --visibility private

# Make public
loom share --visibility public

# Share specific thread
loom share <thread-id> --visibility organization

Share with Support

# Share most recent thread with support team
loom share --support

# Share specific thread with support
loom share <thread-id> --support

Private sessions (created with loom private) cannot be shared. They remain local-only.

Configuration

Loom uses a hierarchical configuration system:

1. Default config: Built-in defaults
2. Config file: ~/.config/loom/config.toml (or custom via --config)
3. Environment variables: LOOM_* prefixed vars
4. CLI flags: Highest priority

Example Configuration

[global]
default_provider = "anthropic"
workspace_root = "/home/user/projects"

[logging]
level = "info"
format = "pretty"  # pretty, compact, or json

[tools]
[tools.workspace]
root = "/home/user/code"

Version Information

loom version

Outputs:

• Version number
• Git commit hash
• Build timestamp
• Platform information

Self-Update

loom update

Updates Loom CLI to the latest version from the server.

Advanced Commands

ACP Agent Mode

Run Loom as an Agent Client Protocol (ACP) agent for editor integration:

loom acp-agent

This mode communicates over stdio and is designed for IDE/editor plugins.

Git Credential Helper

Configure git to use Loom for SCM authentication:

git config --global credential.https://loom.ghuntley.com.helper 'loom credential-helper'

Environment Variables

LOOM_SERVER_URL · string

Default server URL

LOOM_LLM_PROVIDER · string

Default LLM provider (anthropic or openai)

LOOM_AUTO_COMMIT_DISABLE · boolean

Disable automatic git commits (set to “true”, “1”, or “yes”)

LOOM_THREAD_SYNC_URL · string

Thread synchronization server URL

Observability Commands

Loom CLI provides commands for managing crash tracking, cron monitoring, and session analytics.

Crash Tracking

Manage crash projects, issues, and source maps:

# List crash projects
loom crash projects --org <org-id>

# View issues for a project
loom crash issues --project <project-id>

# Upload source maps
loom crash upload-sourcemaps --project <project-id> --release 1.0.0 dist/*.map

# Create a new crash project
loom crash create-project --org <org-id> --name "My App" --platform javascript

# Manage API keys
loom crash api-keys --project <project-id>
loom crash create-api-key --project <project-id> --name "CI Key" --key-type capture

Cron Monitoring

Manage cron monitors and check-ins:

# List monitors
loom crons monitors --org <org-id>

# Create a monitor
loom crons create --org <org-id> --slug daily-backup --name "Daily Backup" --cron "0 2 * * *"

# Send check-in pings
loom crons ping <ping-key>
loom crons ping-fail <ping-key>

# View monitor stats
loom crons stats --org <org-id> --slug daily-backup --period week

# Pause/resume monitoring
loom crons pause --org <org-id> --slug daily-backup
loom crons resume --org <org-id> --slug daily-backup

# Get organization overview
loom crons overview --org <org-id>

Session Analytics

View session health and release adoption:

# List sessions for a project
loom sessions list --project <project-id> --limit 50

# View release health
loom sessions releases --project <project-id>

# Get session stats
loom sessions stats --project <project-id> --period week

Related Pages

REPL Commands

Interactive REPL session commands and tools

Weaver Management

Remote container session management

Authentication

Device code flow and credential management

Crash Tracking

Error and crash capture with source maps

Cron Monitoring

Monitor scheduled jobs and tasks

Session Analytics

Track session health and release adoption