Docs/How-to guides/Choose an interface

Choose an interface

Cantrip ships four ways to drive the same agent core. Pick the one that matches your terminal, browser, or automation workflow.

Overview

Cantrip has four entry surfaces:

If you are unsure, start with the default TUI. It exposes the most agent state at once and is the best fit for day-to-day charm work.

Surface comparison

Surface Start with Best for Main caveat
TUI cantrip Rich interactive sessions with task pane, file tree, logs, traces, and model status visible together Requires a full-screen terminal
Web UI cantrip --web Browser-based chat, easy scrolling/copying, keeping Cantrip beside docs or dashboards --improve is not supported in Web mode
CLI REPL cantrip --no-tui SSH, tmux, minimal terminals, and interactive sessions where plain text is enough No TUI panes or function-key screens
Print mode cantrip run --print "goal" CI, shell pipelines, scheduled jobs, and one-off unattended goals No conversation or REPL; exits when the queue drains

TUI

The default terminal UI is the richest interactive surface. Use it when you want the chat, task list, Juju status, and file tree on screen at once, or when you rely on the function-key screens for logs, traces, the integration graph, transcript browsing, and file detail.

This is the best surface for "build a charm, watch it research, inspect the logs, then confirm the next step" workflows. See TUI screens and shortcuts for the modal screens and hotkeys.

Web UI

The Web UI runs the same live session in a browser tab:

$ cantrip --web
Cantrip Web UI running at http://127.0.0.1:8471

Choose it when a browser is more comfortable than a full-screen terminal: long chat transcripts are easier to scroll, links are easier to follow, and it fits well beside web docs, Grafana, or GitHub in the same window layout.

The important caveat is that --improve is not supported here. Improvement mode relies on interactive confirmation flows that the TUI and CLI REPL provide directly, so use one of those surfaces for existing-charm upgrade work.

CLI REPL

The CLI REPL keeps the session interactive but drops the full-screen UI chrome:

$ cantrip --no-tui

Use it when you are on a remote shell, inside tmux, or in any terminal where a line-oriented interface is easier than a full TUI. The REPL still supports normal chat plus slash commands, and it adds Tab-completion for slash verbs when readline is available.

This is the best fit when you want an interactive session over SSH, need plain-text logs in your terminal history, or prefer to drive the agent with a small command-line footprint.

Print mode

Print mode is deliberately not another interactive surface. It runs one goal to completion, streams progress to stdout, and exits:

$ cantrip run --print "Pack and test this charm"

Use it for CI, shell pipelines, cron jobs, and one-off automation. With --json it emits NDJSON events, which makes it easy to pipe into jq, tee, or log collectors.

If you want back-and-forth conversation, do not use print mode; use the TUI, Web UI, or CLI REPL instead. For the full automation workflow, see Run a single goal non-interactively.

Feature-parity caveats