CLI

Cola CLI is the command-line entry point for the desktop app. It is useful for starting tasks from Terminal, joining the same conversation, checking logs, or connecting Cola to scripts and automation.

Before using the CLI, open the Cola desktop app and sign in. The CLI does not launch the full desktop experience by itself; it connects to a running Cola instance.

Confirm the CLI Is Available

Open Terminal and run:

cola --version

If Terminal says command not found, the current version has not added the cola command to your system path. Follow the installer, release notes, or in-app prompt to enable the CLI entry point.

Check whether Cola is running:

cola status

If the status check fails, open the Cola desktop app first and try again.

Send Your First CLI Task

Use cola message to send a task:

cola message "Summarize what this project in the current directory is for"

The CLI streams Cola's reply. Good terminal tasks include:

cola message "Read README and tell me how to start this project"

cola message "Check recently modified files in the current directory and list risks from high to low"

cola message "Turn this error log into troubleshooting steps a user can follow"

As in the desktop app, for deletion, overwrites, commits, or external messages, ask Cola to list a plan first and wait for confirmation.

Join the Desktop Conversation

By default, the CLI uses a separate CLI session. To join the conversation currently used by the desktop app, specify the session:

cola message "Continue the previous task and summarize the current progress" --session desktop:local

If you want a type of terminal work to keep its own context, use a custom session name:

cola message "Remember that this is my release-check session" --session release-check

The session name separates context. Different sessions do not automatically share the current conversation history.

Include Files

When Cola needs to read a file, include the path in the task:

cola message "Read ./error.log and find the most likely failure cause"

If your CLI version supports attachment parameters, you can pass a path array:

cola message "Analyze these files and summarize them" --attachments '["./report.pdf","./screenshot.png"]'

For paths with spaces, prefer absolute paths or correct quoting.

See Tool Details

Normal output shows the final reply. To see which tools Cola called, add --verbose:

cola message "Check whether the current directory has uncommitted changes" --verbose

For structured output that scripts can read, use JSON:

cola message "Summarize the current project in one sentence" --json

JSON output is useful for automation, but it may contain tool summaries, file paths, and task content. Check it for sensitive information before saving or sharing.

View Logs

For troubleshooting, view today's logs:

cola logs

Show more lines:

cola logs -n 100

Follow logs continuously:

cola logs -f

Logs can contain task content, file paths, or error details. Remove private information before sending them elsewhere.

View and Manage Sessions

List sessions:

cola session list

Show recent content for a session:

cola session show desktop:local

Show only the latest 50 turns:

cola session show desktop:local --limit 50

Deleting a session clears its context. Use this carefully:

cola session delete old-session-name

Cleaning old sessions also removes historical context:

cola session clean --older-than 30d

Before deleting, confirm that you no longer need those records to influence future tasks.

View and Switch Models

List available models:

cola model list

View the current model configuration:

cola model current

Switch to a model in a tier:

cola model set default model-id

The model ID must come from cola model list. New tasks use the updated configuration after switching.

Advanced: Channels and Plugins

If you installed Cola channel plugins, the CLI separates plugin lifecycle from channel connection state. For the full UI and CLI guide, see Channels and Plugins.

cola plugin list
cola plugin install /path/to/plugin-root
cola plugin uninstall plugin-id

Some channels require QR-code login or logout:

cola channel status
cola channel login plugin-id
cola channel logout plugin-id

Channel plugins connect external messaging platforms. Install only plugins you trust, and confirm the plugin source before QR-code login.

FAQ

cola status fails Open the Cola desktop app, wait for the main interface to finish loading, and try again.

A command runs for a long time Longer tasks can take a few minutes. Check the desktop app to see whether it is still running, or view logs from another terminal.

I want to stop the local service You usually do not need to stop it manually. Only when support asks, or when the local service is stuck, run:

cola server stop

After stopping it, reopen the Cola desktop app to prepare the local service again.

Output includes sensitive paths or task content This is normal troubleshooting information. Before sharing command output or JSON, remove private paths, account details, log snippets, and task content.

For more startup, login, and model issues, see Troubleshooting.