sorty CLI Reference

The sorty command-line tool provides comprehensive control over the Sorty application from your terminal. It uses URL schemes to communicate with the main app.

Installation

make install

This installs the sorty CLI script to your system PATH.

Usage

sorty <command> [options]

Environment Variables

SORTY_CLI_DRY_RUN

boolean

default:"0"

When set to 1, prints the URL instead of opening it (useful for debugging)

# Dry run mode - see what URL would be opened
SORTY_CLI_DRY_RUN=1 sorty organize ~/Downloads

Commands

organize

Start organizing a directory with AI-powered file sorting.

sorty organize <path> [--persona <id>] [--auto]

path

string

required

Path to the directory to organize. Can be relative or absolute.

--persona

string

Persona ID to use for organization. Options:

general - Standard categories (Documents, Media, Archives)
developer - Groups by project, language, tech stack
photographer - Organizes by shoots, dates, camera metadata
music_producer - Projects, samples, stems, sessions
student - By subject, course, semester
business - By client, project, fiscal period

--auto

boolean

Automatically start organization without manual confirmation

Examples

# Organize current directory
sorty organize .

# Organize Downloads with developer persona
sorty organize ~/Downloads --persona developer

# Auto-start organization
sorty organize /path/to/folder --auto

# Combine persona and auto-start
sorty organize ~/Documents --persona student --auto

Behavior

Resolves the path to an absolute directory path
Validates that the path exists and is a directory
Opens Sorty with the organization view
URL format: sorty://organize?autostart={true|false}&path={encoded_path}&persona={encoded_persona}

duplicates

Scan a directory for duplicate files using SHA-256 content hashing.

sorty duplicates <path> [--auto]

path

string

required

Path to the directory to scan for duplicates

--auto

boolean

Automatically start scanning without manual confirmation

Examples

# Scan Downloads for duplicates
sorty duplicates ~/Downloads

# Auto-start duplicate scan
sorty duplicates /Volumes/Backup --auto

Output

Opens the Duplicates view in Sorty, where you can:

Review duplicate file groups
Choose which copies to keep
Delete duplicates with safe deletion enabled

status / health

View Workspace Health metrics and analysis.

sorty status
sorty health

Both commands are aliases and open the Workspace Health dashboard.

What You’ll See

Space distribution by file type
Clutter growth rate
Empty folders
Very old files (1+ year)
Broken symlinks
Duplicate candidates
Cleanup opportunities

list

View all watched folders.

sorty list

Alias for sorty watched (with no arguments).

watched

Manage watched folders for automatic organization.

sorty watched              # View watched folders
sorty watched add <path>   # Add a new watched folder

add

subcommand

Add a new directory to the watched folders list

path

string

required

Absolute or relative path to the directory to watch

Examples

# View all watched folders
sorty watched

# Add Downloads to watched folders
sorty watched add ~/Downloads

# Add custom directory
sorty watched add /Volumes/Projects

exclusions

Manage exclusion rules to protect files from organization.

sorty exclusions              # View exclusion rules
sorty exclusions add <pattern> # Add a new exclusion rule

add

subcommand

Add a new exclusion pattern

pattern

string

required

Glob pattern or filename to exclude. Supports wildcards.

Examples

# View all exclusion rules
sorty exclusions

# Exclude all log files
sorty exclusions add "*.log"

# Exclude temporary files
sorty exclusions add "*.tmp"

# Exclude specific directories
sorty exclusions add "node_modules/*"

# Multiple-word patterns need quotes
sorty exclusions add "my important files*"

Common Patterns

Pattern	Description
`*.log`	All log files
`*.tmp`	Temporary files
`.DS_Store`	macOS metadata files
`node_modules/*`	Node.js dependencies
`.git/*`	Git repository data
`*.temp`	Temp files
`Desktop.ini`	Windows metadata

storage

Manage storage locations for organized files.

sorty storage              # View storage locations
sorty storage add <path>   # Add a new storage location

add

subcommand

Add a new storage location

path

string

required

Path to the storage directory

Examples

# View storage locations
sorty storage

# Add external drive as storage
sorty storage add /Volumes/Archive

# Add network storage
sorty storage add /Volumes/NAS/Documents

settings

Open the Settings panel, optionally to a specific section.

sorty settings [section]

section

string

Specific settings section to open. Options:

rules - Exclusion rules
provider - AI provider configuration
strategy - Organization strategy
tuning - AI tuning (temperature, etc.)
automation - Watched folders and automation
finder - Finder integration
notifications - Notification preferences
advanced - Advanced settings
troubleshooting - Troubleshooting tools
help - Help and support

Examples

# Open general settings
sorty settings

# Open AI provider settings
sorty settings provider

# Open exclusion rules
sorty settings rules

# Open advanced settings
sorty settings advanced

persona

Manage organization personas.

sorty persona create                # Open persona creator
sorty persona generate <prompt>     # Generate persona from description

create

subcommand

Open the persona creator interface

generate

subcommand

Generate a new persona using AI from a natural language description

prompt

string

required

Description of the persona you want to create

Examples

# Open persona creator
sorty persona create

# Generate persona for ebook collection
sorty persona generate "I want to organize my sci-fi ebook collection by author"

# Generate persona for photography
sorty persona generate "professional wedding photographer with multiple cameras"

# Generate custom persona
sorty persona generate "music teacher with sheet music and recordings"

Generated Personas

The AI analyzes your description and creates:

Custom system prompt
Appropriate folder structure preferences
File type handling rules
Tagging strategy

rules

Add an exclusion rule (alias for sorty exclusions add).

sorty rules add <pattern>

pattern

string

required

Glob pattern to exclude from organization

Examples

# Exclude cache files
sorty rules add "*.cache"

# Exclude build directories
sorty rules add "build/*"

learnings

Open The Learnings dashboard for managing your AI learning profile.

sorty learnings

Opens the biometric-protected Learnings dashboard where you can:

View learned preferences
Start honing sessions
Review corrections and feedback
Manage learning data

history

View organization history and perform reverts.

sorty history

Opens the History view showing:

Past organization sessions
Files moved in each session
Revert options (Undo with ⌘Z)
Safe deletion recovery

help

Show CLI help message.

sorty help

Displays a summary of all available commands and options.

update

Check for Sorty updates.

sorty update

Opens the Help section with update checking functionality.

Update Process

Queries GitHub Releases API
Compares installed version with latest release
Shows release notes if update available
Provides download link

version

Show the installed version of Sorty.

sorty version
sorty -v
sorty --version

Output Format

Sorty version 1.0.0 (build 42)

Reads version information from /Applications/Sorty.app/Contents/Info.plist.

Error Handling

The CLI provides clear error messages for common issues:

Path Errors

$ sorty organize /nonexistent
Error: Directory does not exist: /nonexistent

$ sorty organize file.txt
Error: Expected a directory path, got: file.txt

Missing Arguments

$ sorty organize
Error: Missing required path. Usage: sorty organize <path> [--persona <id>] [--auto]

$ sorty watched add
Error: Missing required path. Usage: sorty watched add <path>

Unknown Options

$ sorty organize . --unknown
Error: Unknown option for organize: --unknown

Extra Arguments

$ sorty organize . extra args
Error: Unexpected extra argument for organize: extra

URL Encoding

The CLI handles special characters in paths and arguments:

Spaces: My Documents → My%20Documents
Special chars: /path/with spaces & symbols/ → URL-encoded
Unicode: Properly encoded for URL schemes

Requires Python 3 for URL encoding (urllib.parse.quote).

Integration Examples

Shell Aliases

# Add to ~/.zshrc or ~/.bashrc
alias organize='sorty organize'
alias org='sorty organize . --auto'
alias dupes='sorty duplicates'

Git Hooks

#!/bin/bash
# .git/hooks/post-merge
sorty organize . --persona developer --auto

Cron Jobs

# Organize Downloads daily at 2 AM
0 2 * * * /usr/local/bin/sorty organize ~/Downloads --auto

Alfred Workflow

# Organize current Finder folder
tell application "Finder"
  set currentPath to POSIX path of (target of front window as alias)
end tell
do shell script "/usr/local/bin/sorty organize '" & currentPath & "'"

Requirements

macOS 15.0+ (Sequoia)
Sorty.app installed at /Applications/Sorty.app
Python 3 (for URL encoding)
Bash shell

Troubleshooting

Command Not Found

# Check if sorty is in PATH
which sorty

# Re-install if needed
make install

Python 3 Not Found

# Install via Homebrew
brew install python3

App Not Opening

# Verify app is installed
ls /Applications/Sorty.app

# Test URL scheme manually
open "sorty://help"

Dry Run Mode

# See the URL that would be opened
SORTY_CLI_DRY_RUN=1 sorty organize .

CLI Commands

Deeplinks

Developer Guide

​sorty CLI Reference

​Installation

​Usage

​Environment Variables

​Commands

​organize

​Examples

​Behavior

​duplicates

​Examples

​Output

​status / health

​What You’ll See

​list

​watched

​Examples

​exclusions

​Examples

​Common Patterns

​storage

​Examples

​settings

​Examples

​persona

​Examples

​Generated Personas

​rules

​Examples

​learnings

​history

​help

​update

​Update Process

​version

​Output Format

​Error Handling

​Path Errors

​Missing Arguments

​Unknown Options

​Extra Arguments

​URL Encoding

​Integration Examples

​Shell Aliases

​Git Hooks

​Cron Jobs

​Alfred Workflow

​Requirements

​Troubleshooting

​Command Not Found

​Python 3 Not Found

​App Not Opening

​Dry Run Mode

​See Also

sorty CLI Reference

Installation

Usage

Environment Variables

Commands

organize

Examples

Behavior

duplicates

Examples

Output

status / health

What You’ll See

list

watched

Examples

exclusions

Examples

Common Patterns

storage

Examples

settings

Examples

persona

Examples

Generated Personas

rules

Examples

learnings

history

help

update

Update Process

version

Output Format

Error Handling

Path Errors

Missing Arguments

Unknown Options

Extra Arguments

URL Encoding

Integration Examples

Shell Aliases

Git Hooks

Cron Jobs

Alfred Workflow

Requirements

Troubleshooting

Command Not Found

Python 3 Not Found

App Not Opening

Dry Run Mode

See Also