TUI
Flow is the guided terminal UI for workspace-centered Caracal operations.
Audience: User
Context: Use this page if you prefer a guided terminal workflow over direct CLI commands.
Core Explanation
Flow is launched with caracal flow and implemented under caracal/flow. It is not a second backend. It uses the same workspace state, config loading, database models, and command-layer concepts as the in-container CLI.
Its job is to make common operational flows discoverable:
- first-run onboarding
- workspace selection and setup
- principal management
- policy and mandate operations
- delegation inspection
- provider management
- log inspection
- backup and restore entry points
Main Navigation Model
Flow's main menu groups the UI into these top-level areas:
- Principal Hub
- Authority Policy
- Mandate Manager
- Delegation Center
- Authority Ledger
- Operations
- Enterprise
- Settings
- Help and Tutorials
That grouping comes directly from caracal/flow/screens/main_menu.py.
Internal Behavior
At startup, FlowApp:
- configures workspace-local logging
- loads persisted Flow state
- shows the welcome screen
- runs onboarding
- verifies that a usable workspace exists
- enters the main menu loop
Persisted state currently includes:
- onboarding completion
- user preferences such as compact mode
- recent actions
- favorite commands
Session navigation data is intentionally transient.
Onboarding Behavior
Onboarding is not cosmetic. It establishes the workspace and checks runtime expectations such as database configuration and provider-scope catalog loading.
If onboarding cannot produce a valid workspace, Flow exits rather than continuing in a partially configured state.
Practical Usage
Use Flow when:
- you are setting up a workspace for the first time
- you want a guided view of provider and workspace operations
- you want logs and settings without remembering individual CLI groups
Use the CLI when:
- you need exact command output or automation
- you want JSON output
- you are scripting or repeating a workflow
Edge Cases And Constraints
- Flow persists state per workspace, so switching the active workspace changes where Flow reads and writes its state file.
- Flow writes logs to workspace-local files to avoid polluting the TUI with runtime log output.
- Several Flow actions are thin UI wrappers around the same underlying configuration and database modules used by the CLI.