Commands

raucheacho

Commands Reference

Complete guide to all Rosia CLI commands and their options.

Global Flags

These flags work with all commands:

--verbose, -v - Enable verbose logging
--config, -c <path> - Specify custom config file path
--help, -h - Show help for any command

rosia scan

Scan directories to identify cleanable targets.

Usage

rosia scan [paths...] [flags]

Examples

# Scan current directory
rosia scan .

# Scan multiple directories
rosia scan ~/projects ~/workspace

# Scan with depth limit
rosia scan . --depth 5

# Include hidden directories
rosia scan . --include-hidden

# Dry-run (preview without changes)
rosia scan . --dry-run

# Verbose output
rosia scan . --verbose

Flags

Flag	Short	Type	Default	Description
`--depth`	`-d`	int	unlimited	Maximum directory depth to scan
`--include-hidden`		bool	false	Include hidden directories in scan
`--dry-run`		bool	false	Show what would be cleaned without making changes

Output

The scan command displays a table of detected targets:

Found 15 targets:
┌─────────────────────────────────────────────┬──────────┬─────────┐
│ Path                                        │ Size     │ Profile │
├─────────────────────────────────────────────┼──────────┼─────────┤
│ /Users/you/projects/app/node_modules        │ 450 MB   │ node    │
│ /Users/you/projects/api/target              │ 1.2 GB   │ rust    │
│ /Users/you/projects/web/dist                │ 25 MB    │ node    │
└─────────────────────────────────────────────┴──────────┴─────────┘

Total: 1.7 GB across 15 targets

rosia clean

Clean detected targets with confirmation.

Usage

rosia clean [targets...] [flags]

Examples

# Clean with confirmation prompt
rosia clean

# Clean without confirmation (use with caution)
rosia clean --yes

# Clean specific targets
rosia clean ~/projects/app/node_modules ~/projects/api/target

# Skip trash system (permanent deletion)
rosia clean --no-trash --yes

Flags

Flag	Short	Type	Default	Description
`--yes`	`-y`	bool	false	Skip confirmation prompt
`--no-trash`		bool	false	Skip trash system and delete permanently

Confirmation Prompt

By default, Rosia asks for confirmation before cleaning:

About to clean 15 targets (1.7 GB)

Targets:
  - /Users/you/projects/app/node_modules (450 MB)
  - /Users/you/projects/api/target (1.2 GB)
  - /Users/you/projects/web/dist (25 MB)
  ...

Continue? [y/N]:

Output

After cleaning, Rosia displays a summary report:

Cleaning...
✓ Cleaned /Users/you/projects/app/node_modules (450 MB)
✓ Cleaned /Users/you/projects/api/target (1.2 GB)
✓ Cleaned /Users/you/projects/web/dist (25 MB)

Summary:
  Total Size: 1.7 GB
  Files Deleted: 15
  Duration: 5.2s
  Trashed Items: 15

All items moved to trash. Use 'rosia restore --list' to view.

rosia ui

Launch interactive terminal UI for visual selection.

Usage

rosia ui [path] [flags]

Examples

# Launch TUI for current directory
rosia ui .

# Launch TUI for specific path
rosia ui ~/projects

Keyboard Controls

Key	Action
`↑` / `k`	Move cursor up
`↓` / `j`	Move cursor down
`Space`	Toggle selection
`a`	Select all
`n`	Deselect all
`Enter`	Confirm and clean selected targets
`q` / `Esc`	Quit without cleaning

Interface

The TUI displays an interactive list of targets:

┌─ Rosia CLI ─────────────────────────────────────────────────────┐
│                                                                   │
│  Scan Results: 15 targets found (1.7 GB)                        │
│                                                                   │
│  [x] node_modules                    450 MB    node              │
│  [x] target                          1.2 GB    rust              │
│  [ ] dist                            25 MB     node              │
│  [x] build                           120 MB    flutter           │
│  [ ] .dart_tool                      45 MB     flutter           │
│                                                                   │
│  Selected: 3 targets (1.77 GB)                                  │
│                                                                   │
│  [Space] Toggle  [a] Select All  [n] Deselect All  [Enter] Clean│
└───────────────────────────────────────────────────────────────────┘

rosia restore

Restore previously deleted targets from trash.

Usage

rosia restore [id] [flags]

Examples

# List all trashed items
rosia restore --list

# Restore specific item by ID
rosia restore 20250428_143022_node_modules

# Restore with verbose output
rosia restore 20250428_143022_node_modules --verbose

Flags

Flag	Short	Type	Default	Description
`--list`	`-l`	bool	false	List all trashed items

List Output

rosia restore --list

Trashed Items:
┌──────────────────────────────────┬─────────────────────────────┬──────────┬─────────────────────┐
│ ID                               │ Original Path               │ Size     │ Deleted At          │
├──────────────────────────────────┼─────────────────────────────┼──────────┼─────────────────────┤
│ 20250428_143022_node_modules     │ /Users/you/app/node_modules │ 450 MB   │ 2025-04-28 14:30:22 │
│ 20250428_143045_target           │ /Users/you/api/target       │ 1.2 GB   │ 2025-04-28 14:30:45 │
│ 20250427_091530_dist             │ /Users/you/web/dist         │ 25 MB    │ 2025-04-27 09:15:30 │
└──────────────────────────────────┴─────────────────────────────┴──────────┴─────────────────────┘

Total: 3 items (1.7 GB)
Retention: Items older than 3 days will be auto-deleted

Restore Output

rosia restore 20250428_143022_node_modules

Restoring 20250428_143022_node_modules...
✓ Restored to /Users/you/app/node_modules (450 MB)

rosia config

Manage configuration settings.

Usage

rosia config <subcommand> [args] [flags]

Subcommands

show

Display current configuration:

rosia config show

Output:

{
  "trash_retention_days": 3,
  "profiles": ["node", "python", "rust", "flutter", "go"],
  "ignore_paths": [],
  "plugins": [],
  "concurrency": 0,
  "telemetry_enabled": false
}

set

Set a configuration value:

rosia config set <key> <value>

Examples:

# Set trash retention to 7 days
rosia config set trash_retention_days 7

# Set concurrency to 8 workers
rosia config set concurrency 8

# Enable telemetry
rosia config set telemetry_enabled true

# Add ignore path
rosia config set ignore_paths /usr/local,/System

reset

Reset configuration to defaults:

rosia config reset

rosia stats

Display cleaning statistics and history.

Usage

rosia stats [flags]

Examples

# Show statistics
rosia stats

# Show with verbose details
rosia stats --verbose

Output

Rosia Statistics
─────────────────────────────────────────────────────

Total Scans:           42
Total Cleaned:         15.7 GB
Total Files Deleted:   1,234

Average Size by Type:
  node_modules:        500 MB
  target:              100 MB
  dist:                10 MB
  build:               50 MB
  __pycache__:         5 MB

Last Scan:             2025-04-28 14:30:22
Last Clean:            2025-04-28 14:35:10

Disk Space Saved:      15.7 GB

rosia plugin

Manage plugins.

Usage

rosia plugin <subcommand> [args] [flags]

Subcommands

list

List all loaded plugins:

rosia plugin list

Output:

Loaded Plugins:
┌─────────────────┬─────────┬──────────────────────────────────┐
│ Name            │ Version │ Description                      │
├─────────────────┼─────────┼──────────────────────────────────┤
│ rosia-docker    │ 1.0.0   │ Clean Docker images and volumes  │
│ rosia-xcode     │ 1.2.0   │ Clean Xcode derived data         │
└─────────────────┴─────────┴──────────────────────────────────┘

info

Show detailed information about a plugin:

rosia plugin info <plugin-name>

Example:

rosia plugin info rosia-docker

Output:

Plugin: rosia-docker
Version: 1.0.0
Description: Clean Docker images and volumes

Capabilities:
  - Scan for dangling Docker images
  - Clean unused Docker volumes
  - Remove stopped containers

Author: raucheacho
License: MIT

rosia version

Display version information.

Usage

rosia version

Output

Rosia CLI v0.1.0
Built with Go 1.21+
Commit: a1b2c3d
Build Date: 2025-04-28

Exit Codes

Rosia uses standard exit codes:

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	Permission denied
4	Path not found

Environment Variables

Rosia respects these environment variables:

Variable	Description	Default
`ROSIA_CONFIG`	Path to config file	`~/.rosiarc.json`
`ROSIA_TRASH_DIR`	Path to trash directory	`~/.rosia/trash`
`ROSIA_LOG_LEVEL`	Log level (debug, info, warn, error)	`info`

Example:

ROSIA_LOG_LEVEL=debug rosia scan .