Skip to content

cli-reference.md

Latest commit

 

History

History
1795 lines (1208 loc) · 43.1 KB

cli-reference.md

File metadata and controls

1795 lines (1208 loc) · 43.1 KB
Raw

File Organizer CLI Reference

All commands are available through file-organizer or the alias fo.

Core first run commands

Start with this minimal workflow:

fo setup
fo preview ~/Downloads
fo organize ~/Downloads ~/Organized
fo undo

Use fo undo after at least one organize run has been recorded.

See the canonical command sections:

Global Options

These options apply to all commands. You can pass them before or after the command name:

Flag Short Description
--verbose -v Enable verbose output
--dry-run Preview changes without executing
--json Output results as JSON
--yes -y Auto-confirm all prompts
--no-interactive Disable interactive prompts
--help Show help and exit

Top-Level Commands

version

Show the application version.

file-organizer version

start

Run the first-run setup with safe defaults. We recommend this path for beginners.

Usage:

file-organizer start [OPTIONS]

Options:

  • --profile, -p — Profile name (default: default)
  • --dry-run — Preview setup choices without saving configuration

Examples:

# Run quick-start setup
file-organizer start

# Configure a named profile
file-organizer start --profile work

quickstart

Alias of start for quick-start setup.

Usage:

file-organizer quickstart [OPTIONS]

organize

Organize files in a directory using AI models.

Usage:

file-organizer organize INPUT_DIR OUTPUT_DIR [OPTIONS]

Arguments:

  • INPUT_DIR — Directory containing files to organize
  • OUTPUT_DIR — Destination directory for organized files

Options:

  • --dry-run — Preview without moving files
  • --verbose, -v — Verbose output
  • --advanced-help — Show advanced tuning options and exit

Advanced tuning options:

file-organizer organize --advanced-help

Advanced help includes:

  • --max-workers INTEGER — Cap parallel worker count
  • --sequential — Force single-worker sequential processing
  • --no-vision, --text-only — Disable vision model loading and use extension fallback for images
  • --prefetch-depth INTEGER — Parallel task queue-ahead depth (0 disables prefetch queueing)
  • --no-prefetch — Backward-compatible alias for --prefetch-depth 0
  • --transcribe-audio — Transcribe audio files with Whisper and use the transcript for content-aware categorization (requires the [audio] extra; off by default because transcription is the expensive step)
  • --max-transcribe-seconds FLOAT — Skip transcription for audio files longer than this (default: 600; 0 disables the cap)
  • --whisper-model TEXT — Whisper model size for --transcribe-audio: tiny (default), base, small, medium, large-v2, or large-v3. Larger models transcribe more accurately but are slower and need a bigger download
  • --generate-tags — Ask the AI model to attach tags to each organized file during analysis
  • --tag-style TEXT — Tagging domain hint for --generate-tags (sfx, audio, code, descriptive, hierarchical); requires --generate-tags
  • --tag-prompt TEXT — Custom free-text tagging guidance for --generate-tags (max 500 characters); requires --generate-tags

Examples:

# Organize ~/Downloads into ~/Organized
file-organizer organize ~/Downloads ~/Organized

# Preview what would happen (no files moved)
file-organizer organize ~/Downloads ~/Organized --dry-run

# Verbose output
file-organizer organize ~/Downloads ~/Organized --verbose

# Show advanced tuning flags
file-organizer organize --advanced-help

# Limit CPU/IO pressure on constrained machines
file-organizer organize ~/Downloads ~/Organized --max-workers 2 --prefetch-depth 1

# Strict sequential mode for deterministic debugging
file-organizer organize ~/Downloads ~/Organized --sequential

# Disable AI vision processing and use extension-based image fallback
file-organizer organize ~/Downloads ~/Organized --no-vision

# Backward-compatible alias
file-organizer organize ~/Downloads ~/Organized --no-prefetch

# Categorize audio by spoken content (podcasts vs. music vs. voice memos)
file-organizer organize ~/Downloads ~/Organized --transcribe-audio

# Higher-accuracy transcription with a larger Whisper model
file-organizer organize ~/Downloads ~/Organized --transcribe-audio --whisper-model small

# Generate AI tags for each organized file
file-organizer organize ~/Downloads ~/Organized --generate-tags --tag-style descriptive

Note: To set a default methodology (PARA, Johnny Decimal, etc.) or override AI models, use file-organizer config edit before running organize.

preview

Preview how files would be organized without moving them (dry-run shortcut).

Usage:

file-organizer preview INPUT_DIR

Supports the same processing options as organize (--max-workers, --sequential, --no-vision, --prefetch-depth, --transcribe-audio, --max-transcribe-seconds, --whisper-model), plus the AI tag-generation options below — unlike organize, these are always visible (no --advanced-help needed):

  • --generate-tags — Ask the AI model to attach tags to each file during analysis
  • --tag-style TEXT — Tagging domain hint (sfx, audio, code, descriptive, hierarchical); requires --generate-tags
  • --tag-prompt TEXT — Custom free-text tagging guidance (max 500 characters); requires --generate-tags

Examples:

file-organizer preview ~/Downloads
fo preview ~/Downloads

# Preview with AI-generated tags
file-organizer preview ~/Downloads --generate-tags --tag-style sfx

serve

Start the File Organizer web server and API.

Usage:

file-organizer serve [OPTIONS]

Options:

  • --host TEXT — Bind address (default: 0.0.0.0)
  • --port INTEGER — Port number (default: 8000)
  • --reload — Auto-reload on code changes (development mode)
  • --workers INTEGER — Number of worker processes (default: 1)

Examples:

# Start with defaults (port 8000, all interfaces)
file-organizer serve

# Development mode with auto-reload
file-organizer serve --reload

# Custom host and port
file-organizer serve --host 127.0.0.1 --port 9000

# Production with multiple workers
file-organizer serve --workers 4

Access: Once running, open http://localhost:8000/ui/ in your browser.

search

Search for files by name pattern with optional type filtering, or use hybrid BM25+vector semantic search to find files by content relevance.

Usage:

file-organizer search QUERY [DIRECTORY] [OPTIONS]

Arguments:

  • QUERY — Search query (glob pattern like *.pdf, keyword like report, or a natural-language phrase when using --semantic)
  • DIRECTORY — Directory to search in (default: current directory)

Options:

  • --type, -t TEXT — Filter by type: text, image, video, audio, archive
  • --limit, -n INTEGER — Max results to show (default: 50)
  • --recursive / --no-recursive — Search subdirectories (default: recursive)
  • --json — Output as JSON array
  • --semantic — Use hybrid BM25+vector semantic search instead of filename matching; ranks results by content relevance using Reciprocal Rank Fusion

Examples:

# Search by glob pattern
file-organizer search "*.pdf" ~/Documents

# Keyword search (case-insensitive)
file-organizer search "report" ~/Documents

# Filter by type
file-organizer search "*" ~/Pictures --type image

# Non-recursive, limited results
file-organizer search "*.log" /var/log --no-recursive --limit 10

# JSON output for scripting
file-organizer search "*.py" ./src --json

# Semantic search — finds files by content relevance, not just filename
file-organizer search "quarterly budget forecast" ~/Documents --semantic

# Semantic search with type filter and JSON output
file-organizer search "meeting notes" ~/work --semantic --type text --json

analyze

Analyze a file using AI and show its description, category, and confidence score.

Usage:

file-organizer analyze FILE [OPTIONS]

Arguments:

  • FILE_PATH — Path to the file to analyze

Options:

  • --verbose, -v — Show additional details (model name, processing time, content length)
  • --json — Output as JSON

Examples:

# Basic analysis
file-organizer analyze ~/Documents/report.pdf

# Verbose output
file-organizer analyze ~/Documents/report.pdf --verbose

# JSON output for scripting
file-organizer analyze ~/Documents/report.pdf --json

Note: Requires an active model provider configuration (Ollama by default, or another provider configured via FO_PROVIDER and related vars).

tui

Launch the interactive Terminal User Interface.

file-organizer tui

doctor

Scan a directory for file types and recommend optional dependencies.

Usage:

file-organizer doctor PATH [OPTIONS]

Arguments:

  • PATH — Directory to scan for file types

Options:

  • --install — Automatically install recommended dependency groups
  • --json — Output results as JSON

setup

Interactive setup wizard for first-run configuration.

Usage:

file-organizer setup [COMMAND]

Running setup without a subcommand launches the wizard with default settings.

setup run

Run the setup wizard to configure File Organizer.

file-organizer setup run [OPTIONS]

Options:

  • --mode, -m — Setup mode: quick-start (default) or power-user
  • --profile, -p — Profile name (default: default)
  • --dry-run — Preview configuration without saving

hardware-info

Detect hardware capabilities and print model-sizing recommendations.

Usage:

file-organizer hardware-info [OPTIONS]

Options:

  • --json — Output the hardware profile as JSON

Examples:

# Human-readable hardware summary
file-organizer hardware-info

# JSON output for automation or debugging
file-organizer hardware-info --json

Why it exists: This command exposes the same hardware profile the app uses to choose sane defaults for model size and worker count, which helps explain performance differences across machines.

undo

Undo file operations.

Usage:

file-organizer undo [OPTIONS]

Options:

  • --operation-id INTEGER — Specific operation ID to undo
  • --transaction-id TEXT — Transaction ID to undo (undoes all operations in a transaction)
  • --dry-run — Preview without executing
  • --verbose, -v — Verbose output

Examples:

# Undo the last operation
file-organizer undo

# Undo a specific operation
file-organizer undo --operation-id 42

# Undo all operations in a transaction
file-organizer undo --transaction-id abc123

Behavior notes:

  • --dry-run previews the exact undo action without modifying history.
  • When both selectors are provided, --transaction-id takes precedence over --operation-id.
  • Empty or whitespace-only transaction IDs are rejected instead of being treated as valid input.

redo

Redo previously undone file operations.

Usage:

file-organizer redo [OPTIONS]

Options:

  • --operation-id INTEGER — Specific operation ID to redo
  • --dry-run — Preview without executing
  • --verbose, -v — Verbose output

Behavior notes:

  • --dry-run previews the redo action without changing history.
  • operation_id=0 is treated as a valid operation ID rather than falling back to “redo last”.

recover

Replay or sweep the durable-move journal to recover interrupted cross-device moves.

A crash midway through a cross-device rollback move can leave the durable-move JSONL journal with unfinished started/copied entries (and possibly orphan files on disk). Reconciliation is not automatic — run this command on demand (for example, after a crash) to sweep the journal and complete or roll back the interrupted moves.

Usage:

file-organizer recover [OPTIONS]

Options:

  • --journal PATH — Path to the durable-move journal. Defaults to the shared undo journal.
  • --dry-run — Report planned recovery actions without mutating the journal or disk.

Examples:

# Sweep the default journal
file-organizer recover

# Preview what recovery would do, without touching disk
file-organizer recover --dry-run

# Recover from a specific journal file
file-organizer recover --journal /path/to/durable_move.jsonl

Behavior notes:

  • --dry-run calls the same plan_recovery_actions planner the real sweep uses, so the preview can never drift from the actual run.
  • If the journal does not exist or has no entries, the command reports that there is nothing to recover and exits successfully.
  • Transient filesystem errors during the sweep (permissions, disk full) surface as a clean error message, not a stack trace.

history

View operation history.

Usage:

file-organizer history [OPTIONS]

Options:

  • --limit INTEGER — Maximum number of operations to show (default: 10)
  • --type TEXT — Filter by operation type
  • --status TEXT — Filter by status
  • --stats — Show statistics summary
  • --verbose, -v — Verbose output

Examples:

file-organizer history
file-organizer history --limit 50
file-organizer history --stats

analytics

Display storage analytics dashboard.

Usage:

file-organizer analytics [DIRECTORY] [OPTIONS]

Arguments:

  • DIRECTORY — Directory to analyze (optional; defaults to configured workspace)

Options:

  • --verbose, -v — Verbose output

Examples:

file-organizer analytics
file-organizer analytics ~/Documents

Sub-Commands

benchmark — Performance Benchmarking

Measure file processing performance with statistical output, warmup exclusion, suite selection, and baseline comparison with regression detection.

benchmark run

Run a performance benchmark on a directory of files.

Usage:

file-organizer benchmark run [INPUT_PATH] [OPTIONS]

Arguments:

  • INPUT_PATH — Path to files to benchmark (default: tests/fixtures/)

Options:

  • --iterations INTEGER, -i INTEGER — Number of measured iterations (default: 10, min: 1)
  • --warmup INTEGER, -w INTEGER — Warmup iterations excluded from statistics (default: 3, min: 0)
  • --suite TEXT, -s TEXT — Benchmark suite to run: io, text, vision, audio, pipeline, e2e (default: io)
    • io: file stat/read overhead baseline
    • text: TextProcessor.process_file() path with deterministic benchmark model stubs
    • vision: VisionProcessor.process_file() path with deterministic benchmark model stubs
    • audio: audio metadata extraction + rule-based classification path (uses synthetic metadata only when optional extractor dependencies are unavailable)
    • pipeline: PipelineOrchestrator.process_batch() staged path
    • e2e: full FileOrganizer.organize() pass with real writes in an isolated temp workspace
  • --json — Output results as JSON instead of a Rich table
  • --compare PATH — Path to baseline JSON file for regression comparison
  • --transcribe-smoke — Run a single end-to-end audio transcription smoke test

Output Metrics (JSON schema):

  • suite — Suite name that was run
  • effective_suite — Effective suite semantics used for execution (for example, audio may degrade to io semantics when no audio candidates are available)
  • degraded — true when the run used degraded semantics (skip/fallback), otherwise false
  • degradation_reasons — Stable machine-readable degradation reason codes; empty when degraded is false
  • runner_profile_version — Benchmark runner semantics profile version for baseline compatibility checks
  • files_count — Number of files actually processed by the selected suite semantics
  • hardware_profile — Hardware detection info (CPU, memory, GPU)
  • results.median_ms — Median iteration time in milliseconds
  • results.p95_ms — 95th percentile iteration time
  • results.p99_ms — 99th percentile iteration time
  • results.stddev_ms — Standard deviation of iteration times
  • results.throughput_fps — Throughput in files per second (based on median)
  • results.iterations — Number of measured iterations

When --compare is used, JSON also includes:

  • comparison.deltas_pct.* — Percentage delta versus the baseline for each metric
  • comparison.regression — true if current p95 crossed the regression threshold
  • comparison.threshold — Threshold multiplier used for regression detection — fixed at 1.2 for the CLI (not user-configurable; emitted in the JSON for consumer reference)
  • comparison_profile_warning — Present when comparing against a baseline built with a different runner_profile_version

Regression Detection:

When --compare is provided, compares current results against a baseline JSON file. Flags a regression if p95 exceeds 120% of the baseline p95.

Examples:

# Benchmark files in Downloads with default settings
file-organizer benchmark run ~/Downloads

# Run with 5 iterations, no warmup, JSON output
file-organizer benchmark run ~/Documents --iterations 5 --warmup 0 --json

# Run text suite and compare against baseline
file-organizer benchmark run tests/fixtures/ --suite text --json --compare baseline.json

# Save baseline for future comparison
file-organizer benchmark run tests/fixtures/ --json > baseline.json

Audio suite behavior note:

  • audio intentionally differs from text/vision: it exercises real metadata extraction + classification and only falls back to synthetic metadata when optional extractor dependencies are unavailable.

config — Configuration Management

Manage configuration profiles.

config show

Display the current configuration profile.

file-organizer config show [--profile PROFILE]

Options:

  • --profile TEXT — Profile name (default: default)

config list

List all available configuration profiles.

file-organizer config list

config edit

Edit a configuration profile.

file-organizer config edit [OPTIONS]

Options:

  • --profile TEXT — Profile name to edit (default: default)
  • --text-model TEXT — Set the text model name
  • --vision-model TEXT — Set the vision model name
  • --temperature FLOAT — Set temperature (0.0–1.0)
  • --device TEXT — Set device (auto, cpu, cuda, mps, metal)
  • --methodology TEXT — Set default methodology (none, para, jd)

Examples:

file-organizer config show
file-organizer config show --profile work
file-organizer config edit --text-model qwen2.5:3b-instruct-q4_K_M
file-organizer config edit --device cuda --methodology para
file-organizer config edit --profile work --temperature 0.7

model — AI Model Management

Manage AI models via Ollama.

model list

List available models with their install status.

file-organizer model list [--type TYPE]

Options:

  • --type TEXT — Filter by type: text, vision, or audio

model pull

Download a model via Ollama.

file-organizer model pull MODEL_NAME

Arguments:

  • NAME — Model name to download (e.g. qwen2.5:3b-instruct-q4_K_M)

model cache

Show model cache statistics.

file-organizer model cache

Examples:

file-organizer model list
file-organizer model list --type vision
file-organizer model pull qwen2.5:3b-instruct-q4_K_M
file-organizer model cache

copilot — AI Assistant

Interactive AI copilot for file organisation.

Workflow entry point: Start with copilot chat --dir <DIR> for scoped guidance, then run suggested concrete commands from other sections (for example dedupe, rules, or organize).

copilot chat

Chat with the file-organisation copilot.

file-organizer copilot chat [MESSAGE] [--dir DIRECTORY]

Arguments:

  • MESSAGE — Single message (optional; omit to start interactive REPL)

Options:

  • --dir, -d TEXT — Working directory for file operations

Examples:

# Interactive REPL
file-organizer copilot chat

# Single question
file-organizer copilot chat "Help me organize my photos"

# Scoped to a specific directory
file-organizer copilot chat --dir ~/Documents "What duplicates do I have?"

copilot status

Show the status of the AI copilot engine and available models.

file-organizer copilot status

Displays:

  • Number of available Ollama models
  • Model names (first 5)
  • Copilot readiness status

Examples:

file-organizer copilot status
fo copilot status

daemon — Background File Watcher

Run the file watcher as a background daemon.

daemon start

file-organizer daemon start [OPTIONS]

Common options: --watch-dir PATH, --output-dir PATH

daemon stop

file-organizer daemon stop

daemon status

file-organizer daemon status

daemon watch

Watch a directory for file events and stream them in real-time.

Usage: file-organizer daemon watch WATCH_DIR [OPTIONS]

Arguments:

  • WATCH_DIR — Directory to watch for file events

Options:

  • --poll-interval FLOAT — Seconds between polls (default: 1.0)

Examples:

file-organizer daemon watch ~/Inbox
file-organizer daemon watch ~/Documents --poll-interval 2.0

daemon process

One-shot: organize files in a directory and display a summary.

file-organizer daemon process INPUT_DIR OUTPUT_DIR [OPTIONS]

Arguments:

  • INPUT_DIR — Directory containing files to process
  • OUTPUT_DIR — Destination directory for organized files

Options:

  • --dry-run — Preview changes without moving files

Examples:

file-organizer daemon process ~/Inbox ~/Organized

# Preview without moving
file-organizer daemon process ~/Downloads ~/Organized --dry-run

Displays a summary table with:

  • Total files processed
  • Number of files organized
  • Skipped and failed counts
  • Folder structure created

Examples:

file-organizer daemon start --watch-dir ~/Inbox --output-dir ~/Organized
file-organizer daemon status
file-organizer daemon stop

dedupe — Duplicate File Management

Find and manage duplicate files.

Workflow entry point: Use scan -> report -> resolve in that order so you can review before changing anything.

dedupe scan

Scan a directory for duplicate files.

file-organizer dedupe scan DIRECTORY [OPTIONS]

dedupe report

Generate a duplication report.

file-organizer dedupe report DIRECTORY [OPTIONS]

Arguments:

  • DIRECTORY — Directory to scan

dedupe resolve

Interactively or automatically resolve duplicates.

file-organizer dedupe resolve DIRECTORY [OPTIONS]

Arguments:

  • DIRECTORY — Directory to scan for duplicates

Behavior notes:

  • Automatic strategies prompt for confirmation unless batch mode is enabled.
  • Manual selection and confirmation prompts propagate Ctrl+C cleanly.
  • Dry runs report actual simulated removals and estimated space savings without deleting files.
  • Successful-removal summaries reflect what was actually removed rather than the original selection count.

Examples:

file-organizer dedupe scan ~/Images
file-organizer dedupe report ~/Images
file-organizer dedupe resolve ~/Images

rules — Organisation Rules

Manage copilot organisation rules and rule sets.

Workflow entry point: Use rules preview <DIR> for batch review first, then rules apply <DIR> when the dry run matches expectations.

rules list

List all rules in a rule set.

file-organizer rules list [--set RULE_SET]

rules sets

List available rule sets.

file-organizer rules sets

rules add

Add a new rule to a rule set.

file-organizer rules add RULE_NAME [OPTIONS]

Arguments:

  • NAME — Rule name

Options:

  • --ext TEXT — File extension filter (e.g. .pdf,.docx)
  • --pattern TEXT — Filename glob pattern
  • --action, -a TEXT — Action type: move, rename, tag, categorize, archive, copy, delete (default: move)
  • --dest, -d TEXT — Destination path or pattern
  • --priority, -p INTEGER — Rule priority (higher = runs first; default: 0)
  • --set, -s TEXT — Target rule set (default: default)

rules remove

Remove a rule from a rule set.

file-organizer rules remove RULE_NAME [--set RULE_SET]

Arguments:

  • NAME — Rule name to remove

rules toggle

Enable or disable a rule.

file-organizer rules toggle RULE_NAME [--set RULE_SET]

Arguments:

  • NAME — Rule name to toggle

rules preview

Preview what rules would do against a directory (dry-run).

file-organizer rules preview DIRECTORY [OPTIONS]

Options:

  • --set, -s TEXT — Rule set to evaluate (default: default)
  • --recursive/--no-recursive — Recurse into subdirectories (default: true)
  • --max-files INTEGER — Maximum files to scan (default: 500)

rules apply

Apply enabled rules to files in a directory.

file-organizer rules apply DIRECTORY [OPTIONS]

Arguments:

  • DIRECTORY — Directory to apply rules against

Options:

  • --set, -s TEXT — Rule set to evaluate (default: default)
  • --recursive/--no-recursive — Recurse into subdirectories (default: true)
  • --max-files INTEGER — Maximum files to scan (default: 500)
  • --dry-run — Preview actions only

rules watch

Continuously apply enabled rules to a directory.

file-organizer rules watch DIRECTORY [OPTIONS]

Arguments:

  • DIRECTORY — Directory to watch/apply rules against

Options:

  • --set, -s TEXT — Rule set to evaluate (default: default)
  • --recursive/--no-recursive — Recurse into subdirectories (default: true)
  • --max-files INTEGER — Maximum files to scan (default: 500)
  • --interval FLOAT — Seconds between apply runs (default: 10.0)
  • --once — Run one watch cycle and exit
  • --dry-run — Preview actions only

rules export

Export a rule set to YAML.

file-organizer rules export [--set RULE_SET] [--output FILE]

rules import

Import a rule set from a YAML file.

file-organizer rules import FILE [--set RULE_SET]

Arguments:

  • FILE — YAML file to import

Examples:

# List rules in the default rule set
file-organizer rules list

# Add a rule to move PDFs to a Docs folder
file-organizer rules add move-pdfs --ext .pdf --action move --dest Docs

# Add a rule with glob pattern, high priority
file-organizer rules add archive-old --pattern "*.2022*" --action archive --priority 10

# Preview rules against a directory
file-organizer rules preview ~/Downloads

# Export/import rule sets
file-organizer rules export --set work --output work-rules.yaml
file-organizer rules import work-rules.yaml

suggest — Smart File Suggestions

Generate AI-powered file organisation suggestions using pattern analysis.

suggest files

Generate organisation suggestions for files in a directory.

file-organizer suggest files DIRECTORY [OPTIONS]

Options:

  • --min-confidence FLOAT — Minimum confidence threshold 0–100 (default: 40.0)
  • --max-results INTEGER — Maximum suggestions (default: 50)
  • --json — Output as JSON
  • --dry-run — Preview mode

suggest apply

Apply accepted suggestions.

file-organizer suggest apply DIRECTORY [OPTIONS]

Arguments:

  • DIRECTORY — Directory to organize

suggest patterns

Analyze naming patterns in a directory.

file-organizer suggest patterns DIRECTORY [OPTIONS]

Examples:

file-organizer suggest files ~/Downloads
file-organizer suggest files ~/Documents --min-confidence 60
file-organizer suggest patterns ~/Projects

marketplace — Plugin Marketplace

Browse and manage plugins from the marketplace.

Workflow entry point: marketplace list/search -> marketplace info -> marketplace install -> marketplace installed/updates.

marketplace list

List available plugins.

file-organizer marketplace list [OPTIONS]

Options:

  • --page, -p INTEGER — Page number (default: 1)
  • --per-page INTEGER — Results per page (default: 20)
  • --category, -c TEXT — Filter by category
  • --tag, -t TEXT — Filter by tag (repeatable)

marketplace search

Search the marketplace.

file-organizer marketplace search QUERY [OPTIONS]

marketplace info

Show details for a specific plugin.

file-organizer marketplace info PLUGIN_NAME

Arguments:

  • NAME — Plugin name

marketplace install

Install a plugin.

file-organizer marketplace install PLUGIN_NAME [--version VERSION]

Arguments:

  • NAME — Plugin to install

marketplace uninstall

Remove an installed plugin.

file-organizer marketplace uninstall PLUGIN_NAME

Arguments:

  • NAME — Plugin to uninstall

marketplace review

Add or update a review for a plugin.

file-organizer marketplace review PLUGIN_NAME [OPTIONS]

Arguments:

  • PLUGIN_NAME — Name of the plugin to review

Options:

  • --user TEXT — Reviewer ID (required)
  • --rating INTEGER — Rating from 1 to 5 (required)
  • --title TEXT — Review title (required)
  • --content TEXT — Review text (required)

Examples:

file-organizer marketplace review awesome-plugin \
  --user john_doe \
  --rating 5 \
  --title "Great plugin!" \
  --content "This plugin has saved me hours of work!"

marketplace installed

List installed plugins.

file-organizer marketplace installed

marketplace updates

Check for plugin updates.

file-organizer marketplace updates

marketplace update

Update a specific plugin.

file-organizer marketplace update PLUGIN_NAME

Arguments:

  • NAME — Plugin to update

api — Remote API Client

Interact with a running File Organizer API server.

Organization commands accept --token or --api-key, --base-url, --timeout, and --json. Run file-organizer api COMMAND --help for the complete canonical option surface.

Every fo api ... --json success and failure emits the same versioned top-level envelope as local organization commands: schema_version, outcome, command, and either normalized result fields or error. Connection, DNS, TLS, and timeout failures use transport_error with retryable: true. Exit code 2 covers invalid or missing requests, exit code 3 covers conflicts, plan mismatches, and recovery-required outcomes, and other failures exit 1.

api capabilities

Show which remote capabilities are available through fo api, exposed only through an official SDK, or unavailable.

file-organizer api capabilities [OPTIONS]

Options:

  • --json — Print deterministic machine-readable output

api health

Check API server health.

file-organizer api health [OPTIONS]

Options:

  • --base-url TEXT — API base URL (default: http://localhost:8000)
  • --timeout FLOAT — Request timeout in seconds (default: 30.0)
  • --json — Print JSON output

api login

Authenticate and store access tokens.

file-organizer api login [OPTIONS]

Options:

  • --username TEXT — Login username (required; prompted interactively)
  • --password TEXT — Login password (required; prompted securely)
  • --base-url TEXT — API base URL (default: http://localhost:8000)
  • --timeout FLOAT — Request timeout in seconds (default: 30.0)
  • --save-token PATH — Optional path to save token JSON
  • --json — Print JSON output

api me

Show current authenticated user.

file-organizer api me [OPTIONS]

Options:

  • --token TEXT — Bearer token (required)
  • --base-url TEXT — API base URL (default: http://localhost:8000)
  • --timeout FLOAT — Request timeout in seconds (default: 30.0)
  • --json — Print JSON output

api logout

Invalidate the current session token.

file-organizer api logout [OPTIONS]

Options:

  • --token TEXT — Bearer token (required)
  • --refresh-token TEXT — Refresh token to revoke (required)
  • --base-url TEXT — API base URL (default: http://localhost:8000)
  • --timeout FLOAT — Request timeout in seconds (default: 30.0)

api files

List files via the API.

file-organizer api files PATH [OPTIONS]

Arguments:

  • PATH — Directory to list

Options:

  • --token TEXT — Bearer token
  • --api-key TEXT — API key
  • --base-url TEXT — API base URL (default: http://localhost:8000)
  • --recursive/--no-recursive — Include nested files (default: --no-recursive)
  • --include-hidden/--no-include-hidden — Include hidden files (default: --no-include-hidden)
  • --limit INTEGER — Maximum rows (default: 100)
  • --timeout FLOAT — Request timeout in seconds (default: 30.0)
  • --json — Print JSON output

api scan

Scan a server-side directory with canonical recursion and hidden-file policy.

file-organizer api scan INPUT_DIR [OPTIONS]

Arguments:

  • INPUT_DIR — Server-side directory to scan

api preview

Build a canonical remote organization plan without applying it.

file-organizer api preview INPUT_DIR OUTPUT_DIR [OPTIONS]

Arguments:

  • INPUT_DIR — Server-side source directory
  • OUTPUT_DIR — Server-side destination directory

Use --save-plan PATH to persist the reviewed plan. The command accepts the same recursion, hidden-file, collision, transfer, methodology, media, model, provider, and performance options as local organization, including --generate-tags/--tag-style/--tag-prompt for AI tag generation (see organize above for their semantics).

api organize

Execute a canonical remote request or an exact reviewed plan.

file-organizer api organize INPUT_DIR OUTPUT_DIR [OPTIONS]

Arguments:

  • INPUT_DIR — Server-side source directory
  • OUTPUT_DIR — Server-side destination directory

Organization queues a background job by default. Use --foreground to wait for a result, --plan PATH to execute a reviewed plan, and --idempotency-key TEXT to deduplicate background submissions. In JSON mode, result is null for a queued submission and job contains its job_id and status; foreground execution places the operation result in result and emits job: null.

Accepts the same --generate-tags/--tag-style/--tag-prompt flags as api preview and local organize; with --plan, omitting these flags inherits the reviewed plan's own tag settings.

api job

Inspect one remote organization job.

file-organizer api job JOB_ID [OPTIONS]

Arguments:

  • JOB_ID — Organization job identifier

api jobs

List recent remote organization jobs, optionally filtered by status.

file-organizer api jobs [OPTIONS]

api cancel

Cancel a queued or scheduled organization job.

file-organizer api cancel JOB_ID [OPTIONS]

Arguments:

  • JOB_ID — Organization job identifier

Use --expected-revision INTEGER for optimistic concurrency control.

api rollback

Roll back a completed remote organization job.

file-organizer api rollback JOB_ID [OPTIONS]

Arguments:

  • JOB_ID — Organization job identifier

Use --expected-revision INTEGER for optimistic concurrency control.

api suggest

Request a non-mutating single-file organization suggestion.

file-organizer api suggest FILENAME [OPTIONS]

Arguments:

  • FILENAME — File name to classify remotely

api system-status

Show system status from the API server.

file-organizer api system-status [PATH] [OPTIONS]

Arguments:

  • PATH — Path to inspect (default: .)

Options:

  • --token TEXT — Bearer token
  • --api-key TEXT — API key
  • --base-url TEXT — API base URL (default: http://localhost:8000)
  • --timeout FLOAT — Request timeout in seconds (default: 30.0)
  • --json — Print JSON output

api system-stats

Show system statistics from the API server.

file-organizer api system-stats [PATH] [OPTIONS]

Arguments:

  • PATH — Directory to analyze (default: .)

Options:

  • --token TEXT — Bearer token
  • --api-key TEXT — API key
  • --base-url TEXT — API base URL (default: http://localhost:8000)
  • --max-depth INTEGER — Optional max depth
  • --use-cache/--no-use-cache — Use server-side cache (default: --use-cache)
  • --timeout FLOAT — Request timeout in seconds (default: 30.0)
  • --json — Print JSON output

Default base URL: http://localhost:8000

Examples:

file-organizer api health
file-organizer api health --base-url http://myserver:8000
file-organizer api login
file-organizer api system-status

api-keys — Local API Key Generation

Generate and store local API keys.

api-keys generate

Generate a secure API key and print its bcrypt hash.

file-organizer api-keys generate --output PATH [--prefix PREFIX]

Options:

  • --output, -o PATH — Path to safely store the generated API key
  • --prefix TEXT — API key prefix (default: fo)

Examples:

file-organizer api-keys generate -o api-key.txt
file-organizer api-keys generate -o api-key.txt --prefix fo

update — Application Updates

Manage application updates.

update check

Check for new versions.

file-organizer update check

update install

Install the latest version.

file-organizer update install

update rollback

Revert to the previous version.

file-organizer update rollback

profile — Legacy compatibility shim

profile is currently a compatibility command that prints guidance and exits. Use file-organizer config show --profile <name> and file-organizer config edit --profile <name> for named configuration profiles.

If your runtime exposes profile subcommands, check availability first:

file-organizer --help
file-organizer profile --help

In the current default runtime wiring, file-organizer profile is a compatibility shim and does not expose export/import/merge subcommands. Use named config profiles (config show/edit --profile) and settings import/export in the Web UI.

file-organizer profile

autotag — Auto-Tagging

AI-powered tag suggestions and management.

autotag suggest

Suggest tags for files in a directory.

file-organizer autotag suggest DIRECTORY [OPTIONS]

Options:

  • --top-n, -n INTEGER — Max suggestions per file (default: 10)
  • --min-confidence FLOAT — Minimum confidence % (default: 40.0)
  • --style, -s TEXT — Tagging style preset (sfx, audio, code, descriptive, hierarchical)
  • --prompt, -p TEXT — Custom tagging guidance prompt (max 500 characters)
  • --json — Output as JSON

autotag apply

Apply tags to a file and record for learning.

file-organizer autotag apply FILE_PATH TAG...

Arguments:

  • FILE_PATH — File to tag
  • TAGS — One or more tags to apply

autotag popular

Show the most popular tags.

file-organizer autotag popular [--limit N]

Options:

  • --limit, -n INTEGER — Number of tags to show (default: 20)

autotag recent

Show recently used tags.

file-organizer autotag recent [OPTIONS]

Options:

  • --days INTEGER — Days to look back (default: 30)
  • --limit, -n INTEGER — Number of tags to show (default: 20)

autotag batch

Batch tag suggestion for a directory.

file-organizer autotag batch DIRECTORY [OPTIONS]

Options:

  • --pattern TEXT — File pattern (default: *)
  • --recursive / --no-recursive — Recurse into subdirectories (default: true)
  • --style, -s TEXT — Tagging style preset (sfx, audio, code, descriptive, hierarchical)
  • --prompt, -p TEXT — Custom tagging guidance prompt (max 500 characters)
  • --json — Output as JSON

Examples:

file-organizer autotag suggest ~/Documents
file-organizer autotag apply ~/Documents/report.pdf finance quarterly
file-organizer autotag popular --limit 10
file-organizer autotag recent --days 7
file-organizer autotag batch ~/Documents --pattern "*.pdf" --json

desktop — Native Desktop Window

Launch the File Organizer desktop application as a native OS window powered by pywebview.

Usage:

file-organizer desktop [OPTIONS]
# Or using the short alias:
fo desktop [OPTIONS]

Options:

  • --title TEXT — Window title bar text (default: File Organizer)
  • --width INTEGER — Initial window width in logical pixels (default: 1280)
  • --height INTEGER — Initial window height in logical pixels (default: 800)

The command starts the FastAPI web UI on a random free port in a background thread, waits up to 10 seconds for the server to become ready, then opens a native OS window pointing at the local server.

The process exits cleanly when the window is closed; no background server is left running.

Prerequisites:

  • pip install "local-file-organizer[desktop]" (installs pywebview + uvicorn)
  • Ollama running with at least one model pulled
  • Linux: sudo apt-get install -y libgirepository1.0-dev gir1.2-webkit2-4.1

!!! note The legacy standalone file-organizer-desktop entry point is still supported as a backward-compatibility alias, but the unified fo desktop subcommand is preferred.

Examples:

# Start the desktop window with default settings
fo desktop

# Start with a custom title and window dimensions
fo desktop --title "My Personal Organizer" --width 1024 --height 768

See Desktop App Guide for full documentation.

docs — Project Documentation

Build or serve the local project documentation using mkdocs.

Usage:

file-organizer docs [OPTIONS]
# Or using the short alias:
fo docs [OPTIONS]

Options:

  • --build, -b — Compile the documentation to HTML instead of starting the live-reload server (default: false)
  • --host TEXT — Bind address for the docs server (default: 127.0.0.1)
  • --port INTEGER — Port number for the docs server (default: 8001)

Prerequisites:

  • pip install "local-file-organizer[docs]" (installs mkdocs + mkdocs-material)

Examples:

# Start the live-reload documentation server at http://127.0.0.1:8001/
fo docs

# Start the server on a custom port and bind address
fo docs --host 0.0.0.0 --port 9000

# Build the static HTML documentation to the site/ directory
fo docs --build

Short Alias

Use fo as a short alias for file-organizer:

fo serve
fo organize ~/Downloads ~/Organized
fo search "*.pdf" ~/Documents
fo analyze ~/Documents/report.pdf
fo tui
fo copilot chat
fo dedupe scan ~/Pictures
fo autotag suggest ~/Documents

Getting Help

file-organizer --help
file-organizer COMMAND --help
file-organizer COMMAND SUBCOMMAND --help

For example:

file-organizer rules --help
file-organizer rules add --help
file-organizer suggest --help