> ## Documentation Index
> Fetch the complete documentation index at: https://docs.focusme.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Plan Control

> Start, stop, and list FocusMe plans from the command line for scripting and automation.

FocusMe supports command-line arguments to start, stop, and list plans. This lets you automate plan control from scripts, scheduled tasks, or cron jobs without opening the FocusMe window.

## Syntax

<Tabs>
  <Tab title="Windows">
    ```batch theme={null}
    FocusMe.exe --start "Plan Name"
    FocusMe.exe --stop "Plan Name"
    FocusMe.exe --stop "Plan Name" --password "mypass"
    FocusMe.exe --list
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    /Applications/FocusMe.app/Contents/MacOS/FocusMe --start "Plan Name"
    /Applications/FocusMe.app/Contents/MacOS/FocusMe --stop "Plan Name"
    /Applications/FocusMe.app/Contents/MacOS/FocusMe --stop "Plan Name" --password "mypass"
    /Applications/FocusMe.app/Contents/MacOS/FocusMe --list
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    /Applications/FocusMe/FocusMe --start "Plan Name"
    /Applications/FocusMe/FocusMe --stop "Plan Name"
    /Applications/FocusMe/FocusMe --stop "Plan Name" --password "mypass"
    /Applications/FocusMe/FocusMe --list
    ```
  </Tab>
</Tabs>

| Command                                | Description                             |
| -------------------------------------- | --------------------------------------- |
| `--start "Plan Name"`                  | Start a plan by name                    |
| `--stop "Plan Name"`                   | Stop a plan by name                     |
| `--stop "Plan Name" --password "pass"` | Stop a password-protected plan          |
| `--list`                               | List all plans and their current status |

Plan names are **case-insensitive** — `"Work Mode"` and `"work mode"` both match the same plan.

## How It Works

* **If FocusMe is already running**, the command is sent to the running instance. The result is printed to the console.
* **If FocusMe is not running**, it launches minimized to the system tray, processes the command, prints the result, and stays running to enforce the plan.

This means you can safely call these commands regardless of whether FocusMe is open — it will do the right thing either way.

## Exit Codes

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

| Code | Meaning                                    |
| ---- | ------------------------------------------ |
| `0`  | Success                                    |
| `1`  | Plan not found                             |
| `2`  | Protection denied (plan cannot be stopped) |
| `3`  | Invalid command or communication error     |

## Protection Rules

Starting a plan with `--start` is **always allowed**, regardless of protection settings.

Stopping a plan with `--stop` depends on the plan's protection level:

| Protection Type        | Can Stop via CLI?                         |
| ---------------------- | ----------------------------------------- |
| **None** (unprotected) | Yes                                       |
| **Password**           | Yes, with `--password "correct_password"` |
| **Random Character**   | No — returns exit code `2`                |
| **Enforced**           | No — returns exit code `2`                |

<Warning>Plans with Random Character or Enforced protection cannot be stopped from the command line. This is intentional — these protection modes are designed to prevent you from bypassing your own plans.</Warning>

## Checking Exit Codes

<Tabs>
  <Tab title="PowerShell">
    ```powershell theme={null}
    & "C:\Program Files\FocusMe\FocusMe.exe" --start "Work Mode"
    $LASTEXITCODE
    ```

    The exit code is available in `$LASTEXITCODE`.
  </Tab>

  <Tab title="cmd.exe">
    ```batch theme={null}
    "C:\Program Files\FocusMe\FocusMe.exe" --start "Work Mode"
    echo %errorlevel%
    ```

    The prompt may visually overlap with the output line — this is cosmetic only and does not affect the command.
  </Tab>

  <Tab title="Bash (macOS / Linux)">
    ```bash theme={null}
    /Applications/FocusMe.app/Contents/MacOS/FocusMe --start "Work Mode"
    echo $?
    ```
  </Tab>
</Tabs>

## Use Cases

### Scheduled Focus Time

Start a blocking plan at the same time every day:

<Tabs>
  <Tab title="Windows (Task Scheduler)">
    ```
    Program: "C:\Program Files\FocusMe\FocusMe.exe"
    Arguments: --start "Work Mode"
    Trigger: Daily at 9:00 AM
    ```
  </Tab>

  <Tab title="macOS / Linux (cron)">
    ```bash theme={null}
    # crontab -e
    0 9 * * * /Applications/FocusMe.app/Contents/MacOS/FocusMe --start "Work Mode"
    ```
  </Tab>
</Tabs>

This starts your "Work Mode" plan automatically every morning, even if you forget.

### Script-Based Automation

Chain plan control into scripts to set up your work environment:

<Tabs>
  <Tab title="PowerShell">
    ```powershell theme={null}
    & "C:\Program Files\FocusMe\FocusMe.exe" --start "No Social Media"
    & "C:\Program Files\FocusMe\FocusMe.exe" --start "No Games"
    ```
  </Tab>

  <Tab title="Bash">
    ```bash theme={null}
    /Applications/FocusMe.app/Contents/MacOS/FocusMe --start "No Social Media"
    /Applications/FocusMe.app/Contents/MacOS/FocusMe --start "No Games"
    ```
  </Tab>
</Tabs>

### Network-Based Triggers

Combine with automation tools to start plans based on context — for example, activating a "Work Mode" plan when you connect to your office Wi-Fi network.

### Checking Plan Status

Use `--list` to see which plans are running before taking action:

<Tabs>
  <Tab title="Windows">
    ```powershell theme={null}
    & "C:\Program Files\FocusMe\FocusMe.exe" --list
    ```
  </Tab>

  <Tab title="macOS / Linux">
    ```bash theme={null}
    /Applications/FocusMe.app/Contents/MacOS/FocusMe --list
    ```
  </Tab>
</Tabs>

This prints all your plans with their current status (active, standby, disabled, etc.).