Running SelfControl from the Terminal (Version 3.x)

These instructions apply to SelfControl versions 3.x only. If you're running version 4.0 or later, 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/org.eyebeam.SelfControl
2. When a block is started, the command-line tool is copied to /Library/PrivilegedHelperTools/org.eyebeam.SelfControl. Note that this copy of the helper tool may be a different version than the SelfControl app's version.
3. The helper tool must be run as root (i.e. sudo) and the first argument must be the UID of the current user (i.e. $(id -u $(whoami))).

Commands

--is-running

Checks if a block is currently running.

Returns: YES if a SelfControl block is currently running, NO otherwise

Example:

$ sudo /Applications/SelfControl.app/Contents/MacOS/org.eyebeam.SelfControl $(id -u $(whoami)) --is-running
2020-05-20 11:39:08.037 org.eyebeam.SelfControl[1806:3220904] NO

--install

Starts a new block.

Arguments:

1. Path to saved SelfControl blocklist (use File --> Save Blocklist to generate)
2. Block ending date in ISO 8601 format

Example: $ sudo /Applications/SelfControl.app/Contents/MacOS/org.eyebeam.SelfControl $(id -u $(whoami)) --install /path/to/saved/blocklist.selfcontrol 2020-04-28T08:49:58.157+0000

--checkup

Checks whether the block is finished, and removes it if so. This is run automatically on a regular interval, and should not generally need to be run manually.

Example: $ sudo /Applications/SelfControl.app/Contents/MacOS/org.eyebeam.SelfControl $(id -u $(whoami)) --checkup

--print-settings

Prints out settings from SelfControl's secured setting system (for debug purposes only)

Returns: printout of the SelfControl secured settings

Example:

sudo /Applications/SelfControl.app/Contents/MacOS/org.eyebeam.SelfControl $(id -u $(whoami)) --print-settings
2020-05-20 11:51:42.652 org.eyebeam.SelfControl[2099:3232812]  - Printing SelfControl secured settings for debug: -
2020-05-20 11:51:42.659 org.eyebeam.SelfControl[2099:3232812] {
    AllowLocalNetworks = 1;
    BlockAsWhitelist = 0;
    BlockEndDate = "0001-01-01 00:00:00 +0000";
    BlockIsRunning = 0;
    BlockSound = 5;
    BlockSoundShouldPlay = 0;
    Blocklist =     (
        "facebook.com",
        "youtube.com"
    );
    ClearCaches = 1;
    EvaluateCommonSubdomains = 1;
    IncludeLinkedDomains = 1;
    LastSettingsUpdate = "2020-05-15 21:50:49 +0000";
    SettingsVersionNumber = 12;
    TamperingDetected = 0;
}

--version

Checks the version of the helper tool.

Returns: version string for this helper tool

Example:

$ sudo /Applications/SelfControl.app/Contents/MacOS/org.eyebeam.SelfControl $(id -u $(whoami)) --version
2020-05-20 11:39:08.037 org.eyebeam.SelfControl[1806:3220904] 3.0