CLI Reference
Complete command reference for every spinosa subcommand and flag.
The spinosa CLI manages workspaces, conversion, maintenance, and upgrades.
Getting help
spinosa # Launch the TUI dashboard (main way to use Spinosa)
spinosa help # Show help text
spinosa version # Show installed version
spinosa doctor # Full diagnostic of system health
Workspace management
spinosa create <source>
Create a workspace from a document folder.
spinosa create ~/research/papers
This scans the folder, classifies files by type, copies them into the workspace, and registers it. After creation, run spinosa to open the TUI and start a chat.
Flags: --name, --extensions, --cli, --launch
spinosa add <source>
Add more files to an existing workspace.
spinosa add ~/research/more-papers --workspace my-papers-spinosa
Files are converted and added to the workspace's raw/ directory.
Flags: --workspace, --file, --dir, --extensions
spinosa list
List all registered workspaces.
spinosa list
spinosa list --json # Machine-readable output
spinosa status [workspace]
Check workspace health.
spinosa status
spinosa status my-papers-spinosa
Reports framework version, workspace status, and document tool availability.
Updates
spinosa update [workspace]
Update framework template files in a workspace. Preserves your data.
spinosa update my-papers-spinosa
spinosa update --dry-run # Preview without making changes
spinosa update --force # Override user modifications
spinosa upgrade
Upgrade the Spinosa CLI to the latest version.
spinosa upgrade # Latest stable
spinosa upgrade --channel beta # Beta channel
spinosa upgrade --version 1.0.0 # Specific version
Downloads the installer and verifies checksums automatically. Prompts for confirmation before upgrading.
Maintenance
spinosa startup-autoclean
Clean stale installer files from previous upgrade attempts.
spinosa startup-autoclean
spinosa startup-autoclean --dry-run
spinosa uninstall
Remove Spinosa from your system. Workspace folders stay in place.
spinosa uninstall --yes
File classification
During spinosa create and spinosa add, files are classified automatically:
| Category | File types | What happens |
|---|---|---|
| Text-based | txt, rtf, yaml, toml, css, js, py, md, etc. | Renamed to .md |
| MarkItDown | docx, pptx, xlsx, epub, html, text PDF | Converted to markdown |
| OCR | scanned PDF, jpg, png, webp, heic | OCR-processed to markdown |
| Native | csv, json, xml | Copied unchanged |
| Skipped | video, audio | Left at source |
| Ignored | AGENTS.md, .DS_Store, node_modules, .git | Skipped |
Environment variables
| Variable | Purpose |
|---|---|
SPINOSA_HOME |
Override install directory (default: ~/.spinosa) |
NO_COLOR=1 |
Disable ANSI colors |
USE_GUM=1 |
Use gum for enhanced menus |
SPINOSA_NO_EMOJI=1 |
Disable emoji |
Common tasks
| Task | Command |
|---|---|
| Launch TUI | spinosa |
| Create workspace | spinosa create <folder> |
| Add files | spinosa add <folder> |
| Update workspace templates | spinosa update <workspace> |
| Upgrade CLI | spinosa upgrade |
| List workspaces | spinosa list |
| Check health | spinosa doctor |
| Uninstall | spinosa uninstall --yes |
