> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ghuntley/loom/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
# Build from source
cd crates/loom-cli
cargo build --release

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

## Quick Start

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="login" icon="right-to-bracket">
    Authenticate with Loom services using device code flow
  </Card>

  <Card title="logout" icon="right-from-bracket">
    Log out and clear credentials
  </Card>

  <Card title="resume" icon="rotate-left">
    Resume an existing conversation thread
  </Card>

  <Card title="private" icon="lock">
    Start a local-only session that never syncs
  </Card>
</CardGroup>

## Global Flags

<ParamField path="--config" type="string">
  Path to custom configuration file
</ParamField>

<ParamField path="--workspace" type="string">
  Workspace directory for file operations (defaults to current directory)
</ParamField>

<ParamField path="--log-level" type="string">
  Log level: trace, debug, info, warn, error (overrides config)
</ParamField>

<ParamField path="--json-logs" type="boolean">
  Output logs as JSON (overrides config)
</ParamField>

<ParamField path="--server-url" type="string" default="http://localhost:8080">
  Loom server URL for LLM proxy

  Can also be set via `LOOM_SERVER_URL` environment variable
</ParamField>

<ParamField path="--provider" type="string" default="anthropic">
  LLM provider to use: `anthropic` or `openai`

  Can also be set via `LOOM_LLM_PROVIDER` environment variable
</ParamField>

## Authentication

### Device Code Flow

Loom uses OAuth2 device code flow for authentication:

```bash theme={null}
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

```bash theme={null}
loom --server-url https://loom.ghuntley.com logout
```

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

## Thread Management

### List Threads

```bash theme={null}
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

```bash theme={null}
# 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:

```bash theme={null}
loom private
```

Use this for:

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

### Search Threads

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Share most recent thread with support team
loom share --support

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

<Note>
  Private sessions (created with `loom private`) cannot be shared. They remain local-only.
</Note>

## 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

```toml theme={null}
[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

```bash theme={null}
loom version
```

Outputs:

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

## Self-Update

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
git config --global credential.https://loom.ghuntley.com.helper 'loom credential-helper'
```

## Environment Variables

<ParamField path="LOOM_SERVER_URL" type="string">
  Default server URL
</ParamField>

<ParamField path="LOOM_LLM_PROVIDER" type="string">
  Default LLM provider (anthropic or openai)
</ParamField>

<ParamField path="LOOM_AUTO_COMMIT_DISABLE" type="boolean">
  Disable automatic git commits (set to "true", "1", or "yes")
</ParamField>

<ParamField path="LOOM_THREAD_SYNC_URL" type="string">
  Thread synchronization server URL
</ParamField>

## Observability Commands

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

### Crash Tracking

Manage crash projects, issues, and source maps:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="REPL Commands" icon="terminal" href="/cli/repl">
    Interactive REPL session commands and tools
  </Card>

  <Card title="Weaver Management" icon="cube" href="/cli/weaver">
    Remote container session management
  </Card>

  <Card title="Authentication" icon="key" href="/cli/auth">
    Device code flow and credential management
  </Card>

  <Card title="Crash Tracking" icon="bug" href="/observability/crash-tracking">
    Error and crash capture with source maps
  </Card>

  <Card title="Cron Monitoring" icon="clock" href="/observability/cron-monitoring">
    Monitor scheduled jobs and tasks
  </Card>

  <Card title="Session Analytics" icon="chart-line" href="/observability/sessions">
    Track session health and release adoption
  </Card>
</CardGroup>