Skip to main content
FocusMe accepts command-line options so you can start, stop and list plans from scripts, scheduled tasks or cron jobs without opening the FocusMe window.

​
Options

Plans can be addressed by name or by UUID. Plan names are matched case-insensitively; "Work Mode" and "work mode" refer to the same plan. Use --list to see each plan’s UUID — it is handy when you have plans with similar names.

​
Syntax

In cmd.exe drop the leading &. If you installed with the non-admin installer, use the path shown in your Start Menu shortcut instead of C:\Program Files\FocusMe.

​
How It Works

  • If FocusMe is already running, the command is handed to the running instance. The result is printed to your console and the command returns immediately.
  • If FocusMe is not running, it launches, processes the command once it has finished loading, prints the result and then stays running to enforce the plan.
You can therefore call these commands whether or not FocusMe is open.
On Windows the output appears in the console you ran the command from (PowerShell or Command Prompt). In cmd.exe the prompt may be drawn over the output line — this is cosmetic only.

​
Listing Plans

--list prints one line per plan with its name and current status (for example Active, Standby, Paused, Disabled). When the command is answered by a running instance, a third column shows each plan’s UUID.

​
Quick Timer Plans: --restart and --time

--restart and --time only work with plans whose timing is Quick Timer. Using them on a Weekly Schedule, Pomodoro or Multi-Day plan returns exit code 2 with an explanatory message.
  • --start "Plan" --time 45 starts the plan with a 45-minute session, replacing the session length saved in the plan for this run.
  • --restart "Plan" starts the plan if it is stopped. If it is already active, the timer is reset to the full session length (or to --time if given).
  • When extending, the new length must be greater than the time remaining. Otherwise the command fails with exit code 2 and prints the time that is still left.

​
Exit Codes

Every command returns an exit code you can check in scripts:

​
Protection Rules

Starting a plan with --start is always allowed, whatever its protection settings. Stopping a plan with --stop is checked against the plan’s protection for its current state — the Protection when active challenge while the plan is active, paused or on a break, and the Protection when on standby challenge while it is waiting to start:
Plans with Random or Enforced stop protection cannot be stopped from the command line. This is intentional — the command line is not a back door around the protection you chose. See Plan Protection.

​
Terminal Protection and the CLI

Some System settings watch what you type in a terminal — Protect Terminal Commands and Protect PowerShell History on Windows. Ordinary FocusMe CLI commands (for example FocusMe.exe --start "Work Mode", or FocusMe --list without the extension in PowerShell) are recognised as legitimate: they are not removed from your history and do not count as tampering.
If Block Command Prompt (or Block Terminal / iTerm on macOS) is enabled, terminals are closed while a plan is active. Run your commands from a scheduled task or a script launched outside a terminal instead.

​
Use Cases

​
Scheduled Focus Time

Start a blocking plan at the same time every day:
For most daily routines a Weekly Schedule plan does this without any scripting. The CLI is for triggers FocusMe cannot see itself — a hotkey tool, a home-automation hook, or a script that sets up your whole work environment.

​
Script-Based Automation

​
Checking Status Before Acting

Use the output to decide whether to start or extend a plan — for example, call --restart from a hotkey to top up a Quick Timer session that is nearly over.