Skip to content

Running SelfControl from the Terminal

Jump to bottom
Charlie Stigler edited this page May 19, 2021 · 8 revisions

These instructions apply to SelfControl versions 4.x only. If you're running version 3.0.3 or earlier, follow the instructions on this page.

In some cases, you may want to start a SelfControl block from the command line. This can make it much easier for advanced users to script their SelfControl blocks. This article explains how you can start SelfControl from the command line. If you're not familiar with the command line, this article is not for you. These instructions assume SelfControl is installed in your Applications folder.

General usage notes

  1. The SelfControl helper command-line tool is located inside the SelfControl.app bundle: SelfControl.app/Contents/MacOS/selfcontrol-cli
  2. If you run the selfcontrol-cli binary with no arguments, it will display some usage information and valid commands.
  3. The helper tool may be run with user-level permissions (in which case it will prompt for system admin credentials to start a block), OR it can be run as root (i.e. sudo) non-interactively. If run as root, the --uid argument must be set to the controlling user's UID so SelfControl knows whose settings to read, e.g. --uid 501.
  4. The general usage format for selfcontrol-cli is selfcontrol-cli [--uid <controlling user ID>] <command> [<args>]

Commands

start

Starts a SelfControl block

Arguments

--blocklist <path to saved blocklist file>
--enddate <specified end date for block in ISO8601 format>
--settings <other block settings in JSON format>

Example

$ /Applications/SelfControl.app/Contents/MacOS/selfcontrol-cli start --blocklist /path/to/blocklist.selfcontrol --enddate 2021-02-12T06:53:00Z
# < buncha log spam we should probably get rid of >
2021-05-18 23:27:16.300 selfcontrol-cli[56404:5605405] INFO: Block successfully added.

is-running

Prints YES if a SelfControl block is currently running, or NO otherwise

Example

$ /Applications/SelfControl.app/Contents/MacOS/selfcontrol-cli is-running
2021-05-18 23:32:24.597 selfcontrol-cli[56695:5611142] YES

print-settings

Prints the SelfControl settings being used for the active block (for debug purposes)

Example

$ /Applications/SelfControl.app/Contents/MacOS/selfcontrol-cli print-settings
2021-05-18 23:32:30.545 selfcontrol-cli[56705:5611198]  - Printing SelfControl secured settings for debug: -
2021-05-18 23:32:30.547 selfcontrol-cli[56705:5611198] {
    ActiveBlockAsWhitelist = 0;
    ActiveBlocklist =     (
        "facebook.com",
        "twitter.com"
    );
    AllowLocalNetworks = 1;
    BlockEndDate = "2021-05-19 07:30:00 +0000";
    BlockIsRunning = 1;
    BlockSound = 5;
    BlockSoundShouldPlay = 0;
    ClearCaches = 1;
    EnableErrorReporting = 1;
    EvaluateCommonSubdomains = 1;
    IncludeLinkedDomains = 1;
    LastSettingsUpdate = "2021-05-19 06:27:06 +0000";
    SettingsVersionNumber = 26;
    TamperingDetected = 0;
}

version

Prints the version of the SelfControl CLI tool

Example

$ /Applications/SelfControl.app/Contents/MacOS/selfcontrol-cli version
2021-05-18 23:35:34.335 selfcontrol-cli[56760:5614012] 3.9.10
Clone this wiki locally