Skip to content

Running SelfControl from the Terminal

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 bundle:
  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>]



Starts a SelfControl block


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


$ /Applications/ 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.


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


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


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


$ /Applications/ 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 =     (
    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;


Prints the version of the SelfControl CLI tool


$ /Applications/ version
2021-05-18 23:35:34.335 selfcontrol-cli[56760:5614012] 3.9.10