Usage Examples

Common use cases and example workflows

Usage Examples
Real-world scenarios and workflows with FileFortress CLI

This page provides practical examples and common workflows to help you get the most out of FileFortress CLI. Each example includes step-by-step instructions and expected outcomes.

Before You Start

Make sure you have completed the Getting Started guide and have at least one cloud storage account connected.

Common Workflows

First-Time Setup
Complete setup from installation to first search
View Workflow
Advanced Search
Complex search queries and filtering techniques
View Examples
Metadata Filtering
Search by EXIF data, ownership, hashes, and provider metadata
View Examples
Multi-Cloud Management
Managing files across multiple cloud providers
View Examples
Maintenance Tasks
Regular maintenance and optimization tasks
View Tasks

First-Time Setup Workflow

Complete walkthrough from installation to your first successful file search.

Install & Verify
Initialize Device
Add Cloud Storage
Verify Setup
First Search
Step 1: Install and Verify

After installing FileFortress CLI, verify the installation:

filefortress --version

Expected output: Version number (e.g., "FileFortress CLI v1.2.3")

Step 2: Run the Setup Command (Recommended)

🚀 New users should use this approach! The setup command does everything in one go:

Complete Setup (Recommended)
Use this command for the easiest experience:
filefortress setup

This single command will:

  • Initialize your device (prompts for registration code)
  • Ask if you want to set up a custom password (recommended for security)
  • Optionally create a key file so you don't have to type the password each time
  • Guide you through connecting cloud storage (S3, Google Drive, or OneDrive)
  • Automatically scan your files to build the search index
  • Verify everything is working
Why use the setup command?
  • Simplicity: One command does everything
  • Guided Experience: Interactive prompts guide you through each step
  • Automatic Verification: Ensures everything works correctly
  • Best Practices: Follows the recommended configuration order

Expected outcome: Complete FileFortress setup ready for searching files.

🎉 Setup Complete!

After the setup command finishes, your FileFortress is fully configured and ready to search across all your cloud storage accounts!

Step 2 Alternative: Manual Setup (Advanced Users)

Note: Most users should use the setup command above. This section is for users who prefer manual control.

Manual Device Initialization
filefortress init

Or with specific parameters:

filefortress init --code YOUR_REGISTRATION_CODE
Manual Cloud Storage Connection
# Interactive mode (recommended)
filefortress remotes add gdrive
filefortress remotes add onedrive
filefortress remotes add s3

All remote add commands run in interactive mode by default for wizard-style prompts that guide you through the setup process.

Manual File Scanning
filefortress remotes scan "Remote Name"

You can also use the remote ID (number) instead of the name.

Expected output: Same as setup command, but requires multiple steps.

Step 3: Your First Search

Search for files to verify everything is working:

filefortress find query --extensions pdf,docx --view summary

Or if you used a custom password:

filefortress --key-file filefortress.key find query --extensions pdf,docx --view summary

Expected output: Summary of documents found across your connected storage.

Browsing and Listing Files

Use the ls command to explore your files and folders directly from the command line, including a powerful interactive mode.

Interactive File Explorer

For an interactive, user-friendly way to browse your files, use the default interactive mode. This launches a terminal-based UI where you can navigate folders, view file details, and change display options on the fly.

filefortress ls

Use case: Ideal for exploring your storage without having to remember complex commands. You can easily navigate through your remote directories, sort files, and toggle display formats.

Basic and Long Listings

Get a simple list of files and folders in a specific path:

filefortress ls "My GDrive:/Backups/Photos"

For more details, use the --long format:

filefortress ls "My GDrive:/Backups/Photos" --long

Use case: Quickly check the contents of a directory or get detailed information like file size and modification date.

Recursive and Filtered Listings

List all PNG files recursively within a directory:

filefortress ls --recursive --extensions png --files-only

Find all folders inside a specific remote, sorted by name:

filefortress ls --folders-only --sort name --remote-name "My GDrive"

Use case: Great for quickly finding specific types of files or organizing your directory structure by listing only folders.

Multi-Cloud Management Examples

Examples for managing files across multiple cloud storage providers.

Setting Up Multiple Cloud Accounts

Add multiple cloud storage providers:

# Add Google Drive (interactive - recommended)
filefortress remotes add gdrive
# Follow the wizard-style prompts for Google Drive

# Add OneDrive (interactive - recommended)
filefortress remotes add onedrive
# Follow the wizard-style prompts for OneDrive

# Add Amazon S3 (interactive - recommended)
filefortress remotes add s3
# Follow the wizard-style prompts for S3 (Access Key, Secret Key, bucket selection)

# Verify all connections
filefortress remotes list --detailed
Why use interactive mode?
  • Wizard-style prompts: Step-by-step guidance through the setup process
  • No need to remember parameters: The CLI will ask for what it needs
  • Error prevention: Validates input and provides helpful error messages
  • Easier for beginners: No need to know command-line syntax
Cross-Cloud File Search

Search for the same file across all cloud providers:

filefortress find query --text "project proposal" --extension pdf

This will search across all connected cloud storage accounts and show which provider has the file.

Search specific providers only:

# Search only in Google Drive and Dropbox
filefortress find query --text "presentation" --remote "Google Drive"
filefortress find query --text "presentation" --remote "Dropbox"
Monitoring Cloud Storage Usage

Get comprehensive storage information for each provider:

# Get detailed storage information
filefortress remotes info "Google Drive" --refresh
filefortress remotes info "Dropbox" --refresh
filefortress remotes info "OneDrive" --refresh

Shows storage usage, account details, and sync statistics.

Synchronized Scanning

Scan all remotes to keep the index up-to-date:

# Scan all remotes
filefortress remotes scan --background

# Scan specific remote (by name or ID)
filefortress remotes scan "Google Drive"
filefortress remotes scan 1 # Using remote ID

# Check scan status
filefortress remotes list

Regular Maintenance Tasks

Keep your FileFortress installation running smoothly with these maintenance routines.

Daily Maintenance (5 minutes)
# Check for CLI updates
filefortress update --check

# Quick scan of all remotes (by name or ID)
filefortress remotes scan "My Google Drive"
filefortress remotes scan 1 # Using remote ID

# Check storage information
filefortress remotes info "My Google Drive"

Purpose: Ensure you have the latest features and your file index is current.

Weekly Maintenance (15 minutes)
# Scan all remotes
filefortress remotes scan

# Check for duplicate files
filefortress find duplicates --method hash --min-size 1MB

# Review large files
filefortress find query --size-min 50MB --format table

# Update CLI if needed
filefortress update

Purpose: Deep maintenance to identify duplicates and large files, ensure complete indexing.

Monthly Maintenance (30 minutes)
# Review and clean configuration
filefortress config list

# Check device information
filefortress device info

# Review old files (potential cleanup)
filefortress find query --modified-before $(date -d "1 year ago" +%Y-%m-%d) --size-min 10MB

# Enrich metadata for better search
filefortress remotes enrich

# Get comprehensive storage information
filefortress remotes info "My Google Drive" --refresh

Purpose: Comprehensive maintenance including metadata enrichment and configuration review.

Troubleshooting Common Issues

Search Returns No Results

Problem: Search commands return empty results even though files exist.

Solution:

# Check if remotes are connected
filefortress remotes list

# Perform scan
filefortress remotes scan

# Try a broader search
filefortress find query --limit 10
Remote Connection Issues

Problem: Cloud storage connection fails or shows as disconnected.

Solution:

# Check remote status
filefortress remotes show "Remote Name"

# Remove and re-add the remote
filefortress remotes remove "Remote Name"
filefortress remotes add

# Check storage information
filefortress remotes info "Remote Name" --refresh
Device Not Registered

Problem: Commands fail with "device not registered" error.

Solution:

# Check device status
filefortress device info

# Re-initialize if needed
filefortress init --code YOUR_CODE
Device Accidentally Removed from Web Portal

Problem: Your device was working, but you accidentally removed it from the FileFortress web portal and now it cannot sync.

Solution: Use the reinit command with a new registration code from the portal.

# Get a new registration code from the web portal

# Run the reinit command with the new code
filefortress reinit --code <your-new-registration-code>

# If you use a custom password, provide it as well
filefortress --password yourSecretPassword reinit --code <your-new-registration-code>

This will re-link your device to your account without affecting your local data or password settings.

Password Required Error

Problem: Commands fail with "This database requires a password!" error.

Cause: You set up a custom password during initialization but didn't provide it.

Solution:

# Use your password directly
filefortress --password yourCustomPassword remotes list

# OR use your key file (if you created one)
filefortress --key-file path/to/your.key remotes list

# If you forgot your password, you'll need to reinitialize
filefortress --password newPassword init --code YOUR_CODE
Key File Not Working

Problem: "Failed to read password from key file" error.

Possible Causes: Missing files, wrong path, or file corruption.

Solution:

# Check if both .key and .store files exist
ls -la filefortress*.key filefortress*.store

# Try with absolute path
filefortress --key-file /full/path/to/your.key remotes list

# As fallback, use password directly
filefortress --password yourPassword remotes list

# Recreate key file if corrupted
filefortress --password yourPassword init --code YOUR_CODE --create-key-file
Cannot Use Both Password and Key File

Problem: "Cannot specify both --password and --key-file options!" error.

Solution: Choose only one authentication method per command.

# Wrong - using both
filefortress --password myPass --key-file my.key remotes list

# Correct - use either password OR key file
filefortress --password myPass remotes list
# OR
filefortress --key-file my.key remotes list

Automation Examples

Automate common tasks with scripts and scheduled commands.

Bash Scripts PowerShell Scripts Scheduled Tasks

Bash Scripts (Linux/macOS)

Daily Backup Check Script
#!/bin/bash
# daily-check.sh

echo "=== FileFortress Daily Check ==="
echo "Date: $(date)"

# Check for updates
echo "Checking for updates..."
filefortress update --check

# Scan remotes
echo "Scanning remotes..."
filefortress remotes scan

# Check storage information
echo "Checking storage information..."
filefortress remotes info "My Google Drive"

echo "Daily check complete!"
Find Large Files Script
#!/bin/bash
# find-large-files.sh

SIZE_THRESHOLD=${1:-100MB}
OUTPUT_FILE="large-files-$(date +%Y%m%d).csv"

echo "Finding files larger than $SIZE_THRESHOLD..."
filefortress find query --size-min "$SIZE_THRESHOLD" --format csv > "$OUTPUT_FILE"

echo "Results saved to $OUTPUT_FILE"
echo "Total large files found: $(wc -l < "$OUTPUT_FILE")"
Add Cloud Storage Interactively:
# Add any supported cloud storage with wizard-style prompts
filefortress remotes add gdrive
filefortress remotes add onedrive
filefortress remotes add s3
Starts an interactive session to add cloud storage. Each provider will guide you through the setup process with step-by-step prompts, making it easy to configure without remembering command-line parameters.
Advanced Metadata Search Script:
#!/bin/bash
# metadata-photo-search.sh

COUNT_THRESHOLD=${1:-100}

echo "Finding Canon photos taken after 2020..."
filefortress search "" --media-type image \ --meta "exif.cameraMake=Canon" \ --meta "exif.takenAt>=2020-01-01" \ --meta "image.width>=4000" \ --view summary

echo "Finding unshared company files..."
filefortress find query \ --meta "owner.email~=company.com" \ --meta "sharing.shared=false" \ --save-query "company-private-files"

PowerShell Scripts (Windows)

Weekly Maintenance Script
# weekly-maintenance.ps1

Write-Host "=== FileFortress Weekly Maintenance ===" -ForegroundColor Green
Write-Host "Date: $(Get-Date)" -ForegroundColor Yellow

# Update CLI
Write-Host "Updating CLI..." -ForegroundColor Cyan
& filefortress update

# Scan all remotes
Write-Host "Scanning all remotes..." -ForegroundColor Cyan
& filefortress remotes scan

# Find duplicates
Write-Host "Finding duplicate files..." -ForegroundColor Cyan
& filefortress find duplicates --method hash --min-size 1MB

Write-Host "Weekly maintenance complete!" -ForegroundColor Green

Scheduled Tasks

Linux/macOS Cron Jobs
# Edit crontab: crontab -e

# Daily scan at 9 AM
0 9 * * * /usr/local/bin/filefortress remotes scan

# Weekly scan on Sundays at 2 AM
0 2 * * 0 /usr/local/bin/filefortress remotes scan

# Monthly storage info check on 1st of month at 8 AM
0 8 1 * * /usr/local/bin/filefortress remotes info "My Google Drive" --refresh
Windows Task Scheduler

Create scheduled tasks using Windows Task Scheduler:

  1. Open Task Scheduler
  2. Create Basic Task
  3. Set trigger (daily, weekly, etc.)
  4. Action: Start a program
  5. Program: filefortress.exe
  6. Arguments: remotes scan