Skip to content

feat(cli): add command-line arguments for mode, source, and parameter… - #70

Merged
mahlquistj merged 3 commits into
mahlquistj:mainfrom
shadowmkj:main
Aug 15, 2026
Merged

mahlquistj merged 3 commits into
mahlquistj:mainfrom
shadowmkj:main

Conversation

@shadowmkj

Copy link
Copy Markdown
Contributor

Summary

This PR adds command-line arguments (--mode, --source, --param) to allow starting Octotype sessions directly from terminal scripts, desktop shortcuts, or shell commands without requiring manual UI navigation.

Closes #15


Features Added

1. Pre-selecting Mode (--mode / -m)

Passing --mode <mode_name> pre-selects the requested mode and opens Octotype directly at the Source Selection screen.

octotype --mode "WordRace"

2. Instant Session Start (--mode + --source)

Passing both --mode <mode_name> and --source <source_name> launches directly into the word loader and typing session:

octotype --mode "WordRace" --source "brownfox"

3. Parameter Overrides (--param / -P)

Passing one or more --param "<name>:<value>" options overrides parameters for the selected mode and source combination:

octotype --mode "WordRace" --source "brownfox" --param "words:50" --param "time (seconds):30"

Implementation Details

  • CLI Parsing (src/main.rs): Extended AppArgs struct using clap. Enforces strict dependency chains (--source requires --mode, --param requires --source).
  • Parameter Mutation & Validation (src/config/parameters.rs):
    • Implemented Parameter::set_value_from_str for in-place mutation with bounds checking for Range definitions, case-insensitive string selection, boolean toggle parsing, and fixed parameter locking.
    • Added unit test suite covering range, selection, toggle, and fixed parameter errors.
  • Session Builder Pattern (src/page/menu.rs):
    • Introduced SessionBuilder<'a> to handle mode/source resolution, parameter combination, mode overrides, CLI parameter application, and loader creation.
    • create_cli_session uses SessionBuilder for clean, fluent session construction.
  • Pre-TUI Error Handling: Pre-validates flags before initializing ratatui. Invalid modes, sources, or parameters output a clean error to stderr and exit with status code 1.
  • Documentation (README.md): Updated the CLI Arguments reference table with -m/--mode, -s/--source, and -P/--param.

Testing

  • Verified --help output formatting.
  • Added 4 unit tests for parameter parsing in src/config/parameters.rs.
  • Tested all 7 unit tests with cargo test (all passing cleanly).
  • Verified invalid argument handling for non-existent modes, non-existent sources, and invalid parameter formats.

Clean up formatting and styling across app, parameters, and menu modules, including making SessionBuilder::new a const function and adjusting code block layouts.
mahlquistj
mahlquistj previously approved these changes Aug 12, 2026

@mahlquistj mahlquistj left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍

I'll test it myself before i release it properly - Thank you for contributing 😊

@mahlquistj

mahlquistj commented Aug 12, 2026 •

Copy link
Copy Markdown
Owner

Some pedantic lint errors are shown in the CI. You can ignore the "Check Version Updated" 👍 I'll merge when the lints are fixed 😁

@shadowmkj

Copy link
Copy Markdown
Contributor Author

Hi.. the CI errors should pass now. I have not changed the version number like you told me.
I don't now how I dismissed your review, I'm new to contributing. I pushed a new commit that fixes the CI run, that somehow dismissed your review. 😅

@mahlquistj
mahlquistj merged commit ae7d714 into mahlquistj:main Aug 15, 2026
4 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Jump directly to a mode and source from the CLI

2 participants