lattice-ctl CLI Reference

The lattice-ctl command-line tool is your primary interface for controlling the Lattice daemon. Think of it as the control panel for your local AI infrastructure—it lets you start and stop the daemon, manage conversation sessions, launch autonomous agents, and configure which LLM providers you're using.

Installation

When you install Lattice, lattice-ctl comes along automatically. The installation script handles everything:

curl -fsSL https://uselovelace.com/lattice/install.sh | sh

After installation completes, verify that the CLI is available on your system:

lattice-ctl --version

You should see the version number printed to your terminal. If you don't, the installation script will provide guidance on adding the binary to your PATH.

Your First Commands

Let's get the daemon running and verify everything works. Start by launching the daemon process in the background:

lattice-ctl daemon start

The daemon will start up, create necessary directories, and begin listening for connections. Once it's ready, you can verify it's responsive with a simple health check:

lattice-ctl ping

If everything is working, you'll see "pong" printed back to you. To get more detailed information about what the daemon is doing, check its status:

lattice-ctl status

This shows you the daemon version, how long it's been running, and how many agents or sessions are currently active. When you're done and want to shut everything down cleanly:

lattice-ctl daemon stop

The daemon will finish any in-flight work, save its state, and exit gracefully.

How Commands Are Structured

Every lattice-ctl command follows the same pattern. You start with the command name, optionally provide global flags, specify which operation you want to perform, and then provide any arguments that operation needs:

lattice-ctl [OPTIONS] <COMMAND> [ARGS]

The two most useful global options work across all commands. The --socket flag lets you point to a different Unix socket if you're running multiple daemons or testing a custom setup. The --format flag controls whether output is human-readable text (the default) or machine-parseable JSON, which is essential for scripting:

lattice-ctl --format json status

Understanding the Command Categories

Daemon Control

The daemon is the core process that manages everything else. These commands control its lifecycle. When you need to quickly check if the daemon is alive, lattice-ctl ping sends a simple health check and waits for a response. For more detailed information about what the daemon is doing, lattice-ctl status shows metrics like uptime, active agents, and current load. If you want to inspect the health of individual components, lattice-ctl health breaks down status by subsystem. Finally, when you're ready to shut down, lattice-ctl shutdown tells the daemon to exit gracefully after finishing current work.

The daemon control guide covers all the details about starting, stopping, and monitoring the daemon process.

Sessions

Sessions represent conversation threads with persistent history. They're how Lattice keeps track of context across multiple interactions. When you want to see all your conversations, lattice-ctl sessions list shows everything you've created. To inspect a specific conversation and its metadata, lattice-ctl sessions get <id> retrieves full details. Creating a new conversation session requires specifying which workspace it belongs to with lattice-ctl sessions create --workspace-id <id>. When you're done with a conversation, lattice-ctl sessions delete <id> removes it permanently.

The sessions guide explains session management in depth, including how to filter, search, and work with session history.

Agents

Agents are autonomous workers that execute tasks in the background. Unlike interactive sessions, agents run independently and can perform long-running work while you focus on other things. To see what agents are currently running, use lattice-ctl agents list. Starting a new agent requires giving it a unique name with lattice-ctl agents start --name <name>. When you need to stop an agent before it completes, lattice-ctl agents stop <id> sends it a shutdown signal.

The agents guide covers how to launch, monitor, and manage autonomous agents effectively.

Providers

Providers are the LLM services that power your agents and sessions—whether that's local models like Ollama or cloud APIs like Anthropic. The lattice-ctl provider list command shows which providers are configured and enabled. To see detailed configuration for a specific provider, use lattice-ctl provider show <id>. Before relying on a provider, you can test its connectivity with lattice-ctl provider test <id>, which verifies network access and authentication. To see which models a provider offers, lattice-ctl provider models <id> queries the provider's available models.

The providers guide walks through setting up, testing, and troubleshooting provider configurations.

Common Workflows

Let's walk through some typical scenarios you'll encounter when using Lattice.

Starting Lattice for the First Time

When you first install Lattice, you need to get the daemon running before you can do anything else. Start the daemon with lattice-ctl daemon start, which launches the background process and sets up all necessary directories and configuration. Give it a moment to initialize, then verify it's responsive by running lattice-ctl ping. You should see "pong" as confirmation. To get a fuller picture of what's running, check lattice-ctl status, which shows you version information, uptime, and current activity.

Creating and Using a Session

Sessions let you have persistent conversations that maintain context. To create one, you'll need to specify which workspace it belongs to using lattice-ctl sessions create --workspace-id default --title "My Chat". The daemon will return a session ID that you can use to interact with this specific conversation. If you want to see all your sessions, run lattice-ctl sessions list to get an overview. To inspect a specific session and see its full details including message count and timestamps, use lattice-ctl sessions get session_abc123, replacing the ID with your actual session identifier.

Testing Provider Connectivity

Before relying on an LLM provider, it's smart to verify everything is configured correctly. Start by listing all configured providers with lattice-ctl provider list to see what's available. Pick the one you want to test—let's say Ollama—and run lattice-ctl provider test ollama to verify the daemon can reach it. If the test passes, you can see which models are available by running lattice-ctl provider models ollama, which queries the provider for its model list.

Shutting Everything Down

When you're finished working, you can cleanly shut down the daemon. The simplest approach is lattice-ctl shutdown, which sends a shutdown command via the IPC socket. The daemon will finish any in-flight work, save all state to disk, and exit. Alternatively, you can use lattice-ctl daemon stop, which sends a SIGTERM signal to the process. Both methods are safe and preserve all your data.

Output Formats

Understanding how lattice-ctl presents information helps you use it effectively in different contexts.

Human-Readable Text

By default, commands output text formatted for humans to read. When you run lattice-ctl status, you get a clean breakdown showing daemon state, version, PID, uptime in seconds, and counts of active agents, tasks, and sessions. This format makes it easy to quickly scan and understand what's happening.

Machine-Parseable JSON

When you're writing scripts or integrating with other tools, you need structured data. Add --format json to any command to get JSON output instead. Running lattice-ctl status --format json returns a JSON object with a success field, and a data object containing all the same information as the text format, but structured for programmatic access.

This becomes powerful when combined with tools like jq. For example, you can extract just the uptime value with:

STATUS=$(lattice-ctl status --format json)
echo $STATUS | jq '.data.uptimeSeconds'

This pipeline gets the status, pipes it through jq to extract the uptime field, and prints just that value. You can use similar patterns to extract agent counts, check daemon state, or filter session lists.

Environment Variables

Lattice respects several environment variables that let you customize behavior without editing configuration files.

Setting LATTICE_SOCKET to a custom path tells the CLI to connect to a different Unix socket. This is useful when running multiple daemons or testing custom setups. The LATTICE_CONFIG_PATH variable overrides where the daemon looks for its configuration file, letting you maintain multiple configurations for different scenarios. Finally, LATTICE_LOG_LEVEL controls logging verbosity—set it to "debug" when troubleshooting issues, or "warn" for quieter output in production.

Troubleshooting Common Issues

When things go wrong with the CLI, here's how to diagnose and fix the most common problems.

Command Not Found

If your shell can't find lattice-ctl, it means the binary isn't in your PATH. First, verify the installation completed successfully by checking if the binary exists with which lattice-ctl. If you get nothing back, the installation may have failed or the binary might be installed in a non-standard location. Try reinstalling with the installation script, which should handle PATH configuration automatically. On some systems, you may need to restart your terminal or reload your shell configuration after installation.

Connection Refused

When the CLI can't connect to the daemon, you'll see connection refused errors. This usually means the daemon isn't running. Check its status with lattice-ctl daemon status to confirm. If it's not running, start it with lattice-ctl daemon start. Sometimes a stale Unix socket file can cause issues—you can verify the socket exists by checking ~/.lovelace/lattice/daemon.sock. If the socket is missing but the daemon claims to be running, you may have a mismatch between where the daemon created its socket and where the CLI is looking for it.

Permission Denied

Permission errors typically indicate directory permission problems. The daemon needs to create and modify files in ~/.lovelace/lattice/, which requires proper permissions. Check the directory permissions with ls -la ~/.lovelace/lattice/ to see if they're too restrictive. You can fix most permission issues by ensuring the directory is owned by your user and has read/write permissions. If you see permission errors even with correct directory permissions, check if any security software or filesystem restrictions are preventing socket access.

Getting Help

Every command in lattice-ctl includes built-in help documentation. Running lattice-ctl --help shows you the overall structure, lists all available commands, and explains global flags. For help with a specific command, add --help after the command name—for instance, lattice-ctl daemon --help shows all daemon-related operations and their options. Subcommands support help too, so lattice-ctl daemon start --help gives you detailed information about starting the daemon, including all available flags and their purposes.

Next Steps

Now that you understand how lattice-ctl works, you can dive deeper into specific areas. The daemon control guide covers everything about managing the daemon process lifecycle. The session management guide explains how to work with conversation sessions in detail. The agent management guide shows you how to launch and monitor autonomous agents. The provider guide walks through configuring and testing LLM providers. Finally, the examples guide demonstrates real-world usage patterns and automation scripts you can adapt for your own needs.