CLI and TUI

Finn has two clients for a session: finn, a full-screen one, and finn chat, a line-mode one. Both start the server when none runs and leave it running when they quit.

Commands #

CommandWhat it does
finn (or finn tui)chat in this folder on the full screen; it needs a terminal
finn chatchat in this folder, line by line
finn -p TASKrun one task and exit; -p - reads it from stdin
finn serverun the server in the foreground
finn login [PROVIDER]set up a provider with its key (Providers)
finn logout [PROVIDER]remove a stored key, or all of them
finn server ACTIONstatus, start, stop, restart or logs of the server
finn export SESSION [PATH]write a session to a Markdown file (Sessions)
finn --versionthe versions of the server and the client

finn --help, finn chat --help, finn tui --help, finn serve --help, finn server --help and finn export --help list every option.

Options of a session #

These work for finn and finn chat:

OptionWhat it does
--session IDresume that session (Sessions); default: a new one
--cwd DIRthe folder of a new session (default: the current folder)
--provider NAMEthe provider of a new session
--model NAMEthe model of a new session
--api NAMEthe model API of a new session: openai or openai_responses
--profile NAMEthe profile of a new session: the tools its model sees (default: build)
--thinkingshow the model's thinking
--yolowith the approvals on, allow the tool calls of the turns this client starts
--state-dir DIRthe folder of server.json (default: FINN_STATE_DIR)

finn chat also takes --delete ID (Sessions) and --server-command (the program that starts a server); finn with one of them runs finn chat.

One task #

finn -p TASK sends one task and exits when the turn ends. The answer goes to stdout and the rest to stderr. With the approvals on, a call that would ask is denied unless you add --yolo. The exit status:

  • 0: the turn ended normally, also after a denied call;
  • 130: the turn was cancelled;
  • 1: anything else, such as a failed send, a busy session or an empty task.

The server #

finn server stop waits for the running turns to end (FINN_DRAIN_MS, a minute by default), and --now cancels them. finn server logs prints the end of the server's log, and -f follows it.

Slash commands #

Type them in either client:

CommandWhat it does
/newa new session in this folder
/resume [N|ID]list the other sessions that hold something; with a number or an id, switch to one
/tree [N|N+]the session's messages; N goes back before message N, N+ after its answer
/fork [N|N+]a new session from before message N (or after its answer)
/clonea new session with this one's history
/export [--force] [PATH]write the session to a Markdown file (Sessions)
/model [PROVIDER/]NAMEchange the model (and provider) from the next turn on; alone, pick or show it
/thinking [low|medium|high|default]show or change the thinking level
/profile [NAME]change the profile between turns (Tab completes it in finn); alone, list them
/compactfold the history into a summary now
/login [PROVIDER]set up a provider (finn)
/logout [PROVIDER]remove a stored key; alone, every one
/stopstop the running turn
/helpthe list
/quitleave; a session with something in it prints how to come back to it (finn --session ID, finn chat --session ID)

Any other /name goes to the agent as a message, so /name of a skill loads that skill, and a slash command puts its prompt there. What /tree, /fork and /compact do is on Sessions.

Slash commands #

A slash command is a prompt you keep in a file and send with /NAME. It is a file NAME.md in ~/.config/finn/commands/ ($XDG_CONFIG_HOME/finn/commands/), or in .finn/commands/ of a trusted project, which wins over yours with a warning.

---
description: Review a change
---
Review $ARGUMENTS: look for bugs first, then for missing tests.
  • /review src/a.agc sends the prompt with $ARGUMENTS replaced by src/a.agc. Without $ARGUMENTS, the text after the name goes after the prompt, after a blank line.
  • The model gets the prompt; your history shows what you typed. The file is read again at each use. A /name of a skill in the prompt loads that skill, as in a message you type.
  • NAME is lowercase letters, digits, - and _; the front matter (only description) is optional, and the file holds at most 64 KiB. Another file there is skipped with a warning (a link counts only when it leads to a file inside the folder), and a broken one fails only its own name. With the approvals on, a change of the model under .finn/ always asks (why).
  • The clients' own commands keep their names: a model.md is skipped. A command wins over a skill of the same name, with a warning.
  • /help lists the session's commands, and finn suggests them after / (read when a session of another folder opens, and again on /help).

Shell commands #

  • !CMD runs CMD in the session folder; the model gets its output with your next message.
  • !!CMD runs it without giving the output to the model.

The command runs as the bash tool would, with a timeout of 10 minutes. It never asks: you typed it. The deny rules refuse it as they refuse a call of bash (how).

Stop #

/stop, Esc (finn) or Ctrl+C (finn chat) stops the running turn or shell command. In finn chat, a second Ctrl+C leaves, and so does Ctrl+C when nothing runs.

Keys of the full screen #

KeyWhat it does
Entersend; during a turn, the turn reads it before its next model call (Sessions)
Alt+Entersend after the running turn ends (a follow-up)
Ctrl+Ja new line
Ctrl+Gedit the prompt in $VISUAL, else $EDITOR (it may hold arguments, as code -w); what the editor saves becomes the prompt, with a large paste as its text. The text goes through a file only you can read in the state folder, removed afterwards. In the editor, Ctrl+C is a key for it and never quits finn
Escstop the running turn
Ctrl+C; Ctrl+D on an empty prompt while nothing runs and no approval waitsquit
Shift+Tabthe next thinking level
Ctrl+Tshow or hide the thinking
Ctrl+Oshow or hide the tool output
@complete a file path of the session folder; the paths come from the server, which walks the folder or runs the command of your config (The files command)
/complete a command; Esc then Enter sends the text as typed. After /model , /resume , /tree , /fork or /thinking the list holds the models, sessions, messages or levels the server gives, starting on the session's model or level: Tab puts the selected one in. Enter runs the command with the row you moved to; otherwise the line is sent as typed, and the command alone opens its picker
Up, Downmove between the rows of the prompt, keeping the column; Up on an empty prompt shows the earlier messages you sent, and while one is shown, Up from its first row and Down from its last row go through them
Ctrl+A, Ctrl+Ethe start or the end of the line
Ctrl+Left, Ctrl+Right, Alt+Left, Alt+Right, Alt+B, Alt+Fthe word before or after; a word move stops at the end of a line
Ctrl+W, Alt+Backspacedelete the word before the cursor; at the start of a line, the line end before it
Ctrl+U, Ctrl+Kdelete to the start or the end of the line
Delete, Ctrl+Ddelete the character after the cursor
PgUp, PgDnscroll
Ctrl+Y, Ctrl+Nallow or deny the call that waits for an approval
Tabmove to the approval panel: y allow, n deny, a allow the same call for the session; Tab or Esc goes back

The mouse answers the keys of a panel, opens a tool call or the thinking, and moves the cursor in the prompt.

The two rows under the prompt:

  • the session folder (~ for your home), its git branch and the first line of the session's first message;
  • the status (ready, YOLO, approval waiting), the counts and the key hints that fit, then the profile (unless it is build), the model and the thinking level on the right.

On a short screen the first row goes first, so an approval keeps its rows.

The counts read ↑4.8k ↓40 R3.6k 75% cached $0.013 15.0%/32k. All but $ are about the last model call: ↑ its whole prompt (the cached part too), ↓ its output, R the prompt read from the cache and the part of the prompt it was, and the prompt as a part of the model's window (its size in tokens while the window is not known). $ is the session's cost, when the catalog has prices.

After the counts, 42 tok/s is how fast the model wrote its last reply: the output tokens of the call, reasoning included, over the time from its first output to its end. While a reply streams, ~42 tok/s is an estimate from its text (about 4 characters a token). The rate stays until the next one, and a narrow row drops it first.

In finn chat, answer an approval with y, n or a and Enter. The answers are on Approvals and security.