powerrules 0.6.0b4

About

PowerRules is a rule-based command automation tool: when the conditions of a rule match, its commands run.

Originally built to shut down a computer at the right moment, it now runs any shell command.

Rules are evaluated from top to bottom and the first match runs its actions in order. Policies have to be trusted first, so modifications of a policy or its scripts do not go unnoticed.

Getting Started

1. Install via pip (Python 3.11+) or download a standalone binary:

pip install powerrules

2. Create a policy file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/LeoTN/PowerRules/main/assets/schema/powerrules_policy.schema.json

rules:
  # Shut down when no backup process is running and the current time is between 23:00 and 01:30
  - name: "Shutdown after nightly backup"
    enabled: true
    conditions:
      and:
        - process:
            name: "backup.exe"
            exists: false
        - datetime:
            between:
              start: "23"
              end: "1:30"
    actions:
      # Windows command
      - name: "Shutdown"
        run: "shutdown /s /t 0"

3. Validate the policy, trust it after reviewing it and evaluate it once. Use --dry-run to see what would happen:

pwru policy validate --policy my-policy.yaml
pwru trust add --policy my-policy.yaml
pwru policy run --once --policy my-policy.yaml --dry-run

Features

Process & Window Matching

Match rules based on processes and window titles.

# Match if process "firefox.exe" is running
- process:
    name: "firefox.exe"
    exists: true

# Match if window with exact title "Firefox" exists
- window:
    title: "Firefox"
    exists: true

Regex Matching

Match process names and window titles using regular expressions with full-string matching.

# Match if process name contains "fire"
- process:
    name: '.*fire.*'
    exists: true
    match:
      type: regex
      case_sensitive: true # This is the default behavior

# Match if window title starts with "firefox" (case insensitive)
- window:
    title: "Firefox.*"
    exists: true
    match:
      type: regex
      case_sensitive: false

Time-based Conditions

Match specific dates, time ranges, weekdays and months. If several of between, weekday and month are configured, all of them must match. The start of a range is inclusive, the end is exclusive.

# Match every day from 23:00 until 1:30 the next morning
- datetime:
    between:
      start: "23"
      end: "1:30"

# Match on Mondays and Fridays
- datetime:
    weekday:
      - "Monday"
      - "Friday"

# Match in June, July and August
- datetime:
    month:
      - "June"
      - "July"
      - "August"

# Match on the whole days 2026-08-21 and 2026-08-22 (the end date 2026-08-23 is not included)
- datetime:
    between:
      start: "2026-08-21"
      end: "2026-08-23"

# Match from 2026-08-21 18:00 until 2026-08-23 6:00
- datetime:
    between:
      start: "2026-08-21 18:00"
      end: "2026-08-23 6:00"

# Match on Saturdays and Sundays from 2026-08-21 until the end of 2026
- datetime:
    between:
      start: "2026-08-21"
      end: "2027-01-01"
    weekday:
      - "Saturday"
      - "Sunday"

# Match on Saturday and Sunday nights in December from 22:00 until 6:00 the next morning
- datetime:
    between:
      start: "22"
      end: "6"
    weekday:
      - "Saturday"
      - "Sunday"
    month:
      - "December"

All values use the local time of the computer, timezones are not supported.

Logical Conditions

Combine multiple conditions using and, or, and not.

# Match if (condition_1 OR condition_2) AND NOT condition_3
- and:
    - or:
        - condition_1: ...
        - condition_2: ...
    - not:
        condition_3: ...

Actions

When a rule matches, its actions run one after another as commands in a shell.

actions:
  # A failing backup does not prevent the remaining actions
  - name: "Backup"
    run: "backup.sh"
    shell: bash
    working_directory: scripts # Relative to the policy file
    env:
      TARGET: "/mnt/backup"
    timeout: 600
    success_exit_codes: [0, 3]
    continue_on_error: true
    trusted_files:
      - scripts/backup.sh # Relative to the policy file (not to working_directory)

  # Start a command in the background without waiting for it
  - run: "notify.sh"
    shell: bash
    wait: false
    trusted_files:
      - scripts/notify.sh

  # Shutting down may require additional permissions on Linux
  - name: "Shutdown"
    run: "systemctl poweroff"

Commands can read the name of their rule and action from the environment variables POWERRULES_RULE_NAME and POWERRULES_ACTION_NAME.

If an action fails (unexpected exit code, timeout or the command cannot be started), the remaining actions are skipped unless continue_on_error is set.

Policy Evaluation

Evaluate a policy with pwru policy run. Without --once, the rules are evaluated every 10 seconds until PowerRules is stopped. A matching rule only runs its actions when it becomes the active match, not on every evaluation while it keeps matching.

# Evaluate continuously
pwru policy run

# Evaluate once and exit
pwru policy run --once

# Only report which rule would match without running any commands
pwru policy run --dry-run

The policy is loaded once at startup, so changes to the file require a restart. Unless --dry-run or --no-require-trust is used, the policy has to be trusted. If a condition cannot be evaluated, an action fails or a trusted file was modified, the evaluation stops.

Trust

PowerRules remembers which policies you trust. A policy is identified by its path and trusted by its content (SHA-256 hash). Every modification makes it untrusted until you review it and trust it again. Files which actions depend on (e.g. scripts or executables) are not detected automatically. To cover them as well, you can list them in the action's trusted_files configuration.

# Trust the current content of a policy and its trusted files
pwru trust add --policy my-policy.yaml

# Show all trusted policies and their current status
pwru trust list

# Remove the trust of a policy
pwru trust remove --policy my-policy.yaml

# Remove trusted policies whose policy file no longer exists
pwru trust prune

Relative paths are resolved against the directory of the policy file:

actions:
  - run: "./backup.sh"
    working_directory: scripts
    trusted_files:
      - scripts/backup.sh # Relative to the policy file (not to working_directory)

pwru policy run refuses to run untrusted policies by default. --no-require-trust can be used to override this behaviour.

The policy and its trusted files are checked when the policy is loaded. Right before an action runs, its trusted_files are checked again. The trust store is saved in ~/.powerrules/trust.json.

Logging

All policy and trust commands accept the following logging options:

pwru policy run --log-level DEBUG --log-file my-log.log

Messages are shown on the console and written to a rotating log file. Commands of actions and their output are only logged on DEBUG level. The error output of a failed action is always logged as an error.

Exit Codes

pwru reports the result of a command via its exit code.

Supported Platforms

Platform independent via pip:

pip install powerrules

Credits & License

• Inkscape → program used to design the logo
• Nuitka → standalone binaries
• psutil → process information
• Pydantic → configuration validation
• PyYAML → YAML policy parsing
• rich → console output formatting
• Typer → command-line interface

This repository is licensed under the MIT License.