Interactive CLI¶
Filoma provides a powerful interactive command-line interface that combines filesystem exploration with data analysis capabilities. Navigate directories with arrow keys, probe files and folders, and analyze the results—all within a beautiful terminal interface.
Overview¶
The CLI is built using modern Python tools for an exceptional user experience:
- Typer: Modern CLI framework with automatic help generation
- questionary: Interactive prompts with arrow-key navigation
- Rich: Beautiful terminal formatting, tables, and progress bars
Getting Started¶
Launch the CLI¶
# Start in current directory
filoma
# Start in specific directory
filoma /path/to/analyze
# Show help
filoma --help
Additional CLI Commands¶
filoma includes built-in commands for specific tasks:
filoma dedup [paths...]: Find and report duplicate files.--cross-dir: Check for duplicates across provided paths.filoma verify [reference] --target [target]: Verify dataset integrity against a reference snapshot/manifest.filoma quality [path]: Run data quality analysis on a dataset.filoma brain chat: Start an interactive chat with the Filoma Brain.
Navigation¶
- Arrow keys: Navigate menus
- Enter: Select option
- Ctrl+C: Exit anytime
Features¶
🗂️ File Browser¶
Navigate your filesystem with an intuitive interface:
- Directory Navigation: Enter folders, go to parent directory
- File Type Icons: Visual indicators for different file types (🖼️ images, 💻 code, 📄 documents)
- Smart Sorting: Directories first, then files, alphabetically sorted
🔍 Probe Operations¶
Analyze files and directories with multiple probe options:
- Auto Probe: Automatically detects and uses the best probe method
- Probe as File: General file analysis using
probe_file() - Probe as Image: Specialized image analysis using
probe_image() - Probe to DataFrame: Directory analysis with
probe_to_df()for data exploration
📊 DataFrame Analysis¶
When you use "Probe to DataFrame", unlock powerful data analysis capabilities:
Core DataFrame Operations¶
- DataFrame Info: Shape, column types, memory usage
- Head Display: View first N rows with customizable count
- Column Overview: All columns with types and sample values
- Basic Statistics: Descriptive statistics for numeric columns
Advanced Column Analysis¶
- Value Counts: Frequency distribution of column values
- Unique Values: List of unique values (with count)
- Column Statistics: Mean, std, min, max for numeric data
- Null Analysis: Missing value counts and percentages
Data Exploration¶
- Interactive Filtering: Filter by column values with live preview
- Search Functionality: Find specific values across columns
- Sample Data: Preview column contents before analysis
Export Options¶
- CSV Export: Standard comma-separated format
- JSON Export: Structured JSON format
- Parquet Export: High-performance columnar format
Example Workflow¶
Here's a typical analysis session:
1. Launch and Navigate¶
filoma ~/projects/my-data
The CLI opens showing your directory contents with file type icons.
2. Explore Directory Structure¶
📁 .. (Parent Directory)
📁 datasets/
📁 images/
💻 analysis.py
📄 README.md
📊 results.csv
Use arrow keys to navigate. Select datasets/ → choose "Enter directory".
3. Probe for Analysis¶
Select the directory you want to analyze → choose "🔍 Probe to DataFrame".
A spinner shows the analysis progress, then results appear:
✅ Probe Results for datasets
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Property ┃ Value ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Total Files │ 1,247 │
│ Total Size │ 2.34 GB │
│ File Types │ 12 │
│ Directories │ 8 │
└───────────────┴───────────────────────────┘
4. Interactive DataFrame Analysis¶
The DataFrame analysis menu automatically appears:
📊 DataFrame Analysis for datasets
Shape: 1,247 rows × 8 columns
What would you like to do with this DataFrame?
> 📊 Show DataFrame Info
👀 Show Head (first 10 rows)
📋 Show Columns
📈 Column Analysis
🔍 Basic Statistics
🔎 Search/Filter
💾 Export Options
🔙 Back to File Browser
5. Explore Your Data¶
View column information:
📋 DataFrame Columns
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Column ┃ Type ┃ Sample Values ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ path │ String │ /datasets/file1.txt, /datasets/... │
│ size_bytes │ Int64 │ 1024, 2048, 4096 │
│ file_type │ String │ .txt, .csv, .json │
│ modified_date │ String │ 2024-01-15, 2024-01-16, ... │
└───────────────┴────────────┴──────────────────────────────────────┘
Analyze specific columns:
Select "📈 Column Analysis" → choose file_type → "📊 Value Counts":
Value counts for 'file_type':
.txt 456
.csv 234
.json 187
.py 156
.md 89
...
6. Export Results¶
Select "💾 Export Options" → "📄 Export to CSV" → enter filename:
✅ Successfully exported to: datasets_analysis.csv
Tips and Tricks¶
Efficient Navigation¶
- Use the parent directory option (
📁 ..) to quickly move up the tree - File type icons help identify content at a glance
- The current directory is always shown in the welcome panel
DataFrame Analysis¶
- Start with "📊 Show DataFrame Info" for a quick overview
- Use "👀 Show Head" to understand your data structure
- "📈 Column Analysis" → "📊 Value Counts" reveals data distributions
- Export results for further analysis in other tools
Performance¶
- Large directories are analyzed with progress bars
- DataFrame operations are optimized for speed
- Filtering shows live previews without affecting the original data
Integration with Python API¶
The CLI uses the same underlying functions as the Python API:
import filoma
# CLI "Auto Probe" uses:
result = filoma.probe("/path/to/analyze")
# CLI "Probe to DataFrame" uses:
df_result = filoma.probe_to_df("/path/to/analyze")
# Access the DataFrame:
df = df_result.df
This means you can seamlessly move between interactive exploration and programmatic analysis.
The interactive CLI makes filesystem analysis accessible and enjoyable, whether you're doing quick exploration or deep data analysis. Its intuitive interface and powerful features make it perfect for both newcomers and advanced users.