Home / Docs / TUI Guide

TUI Guide

How to navigate the Spinosa dashboard, keyboard shortcuts, and all available screens.

The Spinosa TUI (terminal UI) is the main way to use Spinosa. Launch it with:

spinosa

This guide covers navigation, keyboard shortcuts, and each screen.

Screens (routes)

Screen	When you see it	What it does
Home	Default startup screen	Shows recent workspaces, chat prompt, and boot health
Workspace picker	Press `W` or click Workspaces	Lists all registered workspaces, sort and select
Onboarding wizard	Click + New workspace	11-step wizard to create a workspace from documents
Chat session	Select a workspace and ask a question	Chat with your documents through AI agents
Visualizer	Look for Visualizer in top menu	Explore conversation flow, file access, activity timeline
Add-files wizard	Press `I` or click Import files	Add new documents to an existing workspace

Key	Action
`Ctrl+P` or `/`	Command palette
`S`	Settings
`A`	Agents
`K`	Keys / model provider
`W`	Workspaces (workspace picker)
`M`	Models
`N`	New chat session
`I`	Import / add files
`Escape`	Go back or close dialog
`Ctrl+C`	Exit TUI (or cancel current operation)
`↑` `↓` or `j` `k`	Navigate lists
`Enter`	Confirm / open selected
`Tab`	Auto-complete in prompt
`?`	Show help

When you launch spinosa, the home screen shows:

Recent workspaces — up to 4 recently accessed workspaces. Click one to open it.
Chat prompt — at the bottom. Type your question and press Enter.
Boot health — startup checks (version check, workspace index, maintenance)
Footer — keyboard labels for Settings, Agents, Keys, Workspaces, Models If no workspace is active, the chat prompt is empty. Select a workspace first, or create one.

Press W to open the workspace picker. It shows a sortable table:

Column	Description
Name	Workspace name
Parent	Parent folder path
Status	Current setup status
Ver	Framework version
Accessed	Last access time
Click column headers to sort. Use `↑` `↓` to navigate and `Enter` to open. The + New workspace button starts the onboarding wizard.
Stale workspace entries (pointing to deleted folders) can be cleaned up with the Delete stale button in the top header.

When you open a workspace or start a new session, you enter the chat view:

Type your question at the prompt and press Enter
Spinosa agents search your documents, draft a report, and verify the evidence
Reports are displayed inline with evidence quotes, source paths, and verification status
Use ↑ ↓ to scroll through the conversation
Ask follow-up questions in the same chat

The onboarding wizard creates a new workspace from a folder of documents. Steps:

Path — Enter the folder path with your documents
Name — Name the workspace
Tools — Verify document converters are installed
Scan — Classifies files and shows what was found
Import — Choose which file types to import 6–9. Processing — Files are converted in phases
Provider — Choose your AI coding tool
Done — Summary and "Open workspace" button Each processing phase pauses between steps so you can review before proceeding.

Press I from the home screen to add files to an existing workspace. The wizard:

The visualizer shows how your AI agents worked through a question. Open it from the workspace picker or top menu. Three view modes:

Mode	Key	What it shows
Files	`1`	Heatmap of which files in the workspace were accessed
Flow	`2`	Graph of tool calls the agents made, in sequence
Activity	`3`	Timeline of the conversation
Controls:
Key	Action
-----	--------
`1` `2` `3`	Switch modes
`+` `-`	Zoom in/out
`0`	Fit graph to view
`←` `→`	Select marks/nodes
`Enter`	Inspect selected node details
`Shift` + arrows	Pan
Drag	Pan (mouse)
`Ctrl` + wheel	Zoom (mouse)
`e`	Export graph (SVG, CSV, JSON)
`?`	Show help overlay

Press Ctrl+P or / to open the command palette. Type to filter commands:

Press K to configure your AI model provider. You can connect to: