Skip to content

cli.md

Latest commit

 

History

History
193 lines (131 loc) · 3.68 KB

cli.md

File metadata and controls

193 lines (131 loc) · 3.68 KB

Ferrite Command Line Interface

Ferrite supports command-line arguments for opening files and directories directly from the terminal.

Usage

ferrite [OPTIONS] [PATH]...

Arguments

[PATH]... - Files or directories to open

Pass one or more file paths to open them as tabs, or a directory to open it as a workspace.

Examples:

# Open a single file
ferrite README.md

# Open multiple files as tabs
ferrite file1.md file2.md notes.md

# Open current directory as workspace
ferrite .

# Open a specific directory as workspace
ferrite ~/projects/my-project

# Mix of files (first file gets focus)
ferrite README.md CHANGELOG.md docs/getting-started.md

Options

-h, --help

Print help information and exit.

ferrite --help
ferrite -h

-V, --version

Print version information and exit.

ferrite --version
ferrite -V

--log-level <LEVEL>

Set the log level for debugging. This overrides the log_level setting in config.json.

Valid values: debug, info, warn, error, off

# Enable debug logging
ferrite --log-level debug

# Show only errors
ferrite --log-level error

# Disable all logging
ferrite --log-level off

# Combine with file arguments
ferrite --log-level debug README.md

Log Level Precedence:

  1. CLI flag (--log-level)
  2. Config file (config.json)
  3. Built-in default (warn)

Behavior

Opening Files

  • Each file path is opened as a separate tab
  • The first successfully opened file gets focus
  • Non-existent files are logged as warnings and skipped
  • Relative paths are resolved to absolute paths

Opening Directories

  • A single directory can be passed to open it as a workspace
  • The workspace mode enables:
    • File tree navigation
    • Quick switcher (Ctrl+P)
    • Search in files (Ctrl+Shift+F)
    • Git status indicators
  • If multiple directories are provided, only the first one is used

Mixed Arguments

When both files and a directory are provided:

  • The directory becomes the workspace root
  • Files are opened as tabs within that workspace context

Error Handling

  • Non-existent paths produce a warning in the log but don't crash the app
  • Permission errors are logged and the file is skipped
  • Invalid paths (neither file nor directory) are skipped with a warning

Examples

Basic Usage

# Start with empty editor
ferrite

# Edit a markdown file
ferrite ~/Documents/notes.md

# Open project as workspace
ferrite ~/projects/my-rust-project

Shell Integration

# Open file from pipe (not directly supported, use temp file)
# Instead, use shell redirection:
cat file.md | ferrite /dev/stdin  # Linux/macOS

# Edit git commit message
GIT_EDITOR="ferrite" git commit

# Open all markdown files in current directory
ferrite *.md

Scripting

# Check version in scripts
VERSION=$(ferrite --version)
echo "Using $VERSION"

# Conditional launch
if [ -f "README.md" ]; then
    ferrite README.md
fi

Environment Variables

Ferrite reads log configuration from config.json and supports CLI overrides. The RUST_LOG environment variable is no longer used; use --log-level instead.

Method Example Priority
CLI flag ferrite --log-level debug Highest
Config file "log_level": "debug" in config.json Medium
Built-in default warn Lowest

Platform Notes

Windows

# PowerShell
.\ferrite.exe README.md

# CMD
ferrite.exe README.md

# Open current directory
ferrite.exe .

Linux/macOS

# Standard usage
./ferrite README.md

# If installed to PATH
ferrite README.md

Related