phacility/phabricator · warning · PhutilArgumentUsageException

Specify a rule to edit with "--rule <id|monogram>".

Error message

Specify a rule to edit with "--rule <id|monogram>".

What it means

PhutilArgumentUsageException thrown by HeraldRuleManagementWorkflow::execute() (the 'bin/herald rule' workflow) when the --rule argument is missing or empty. This is a usage error printed with the command's help text; nothing has been executed or modified yet.

Source

Thrown at src/applications/herald/management/HeraldRuleManagementWorkflow.php:37

            'help' => pht('Apply changes to this rule.'),
          ),
          array(
            'name' => 'disable',
            'help' => pht('Disable the rule.'),
          ),
          array(
            'name' => 'enable',
            'help' => pht('Enable the rule.'),
          ),
        ));
  }

  public function execute(PhutilArgumentParser $args) {
    $viewer = $this->getViewer();

    $rule_name = $args->getArg('rule');
    if (!strlen($rule_name)) {
      throw new PhutilArgumentUsageException(
        pht('Specify a rule to edit with "--rule <id|monogram>".'));
    }

    if (preg_match('/^H\d+/', $rule_name)) {
      $rule_id = substr($rule_name, 1);
    } else {
      $rule_id = $rule_name;
    }

    $rule = id(new HeraldRuleQuery())
      ->setViewer($viewer)
      ->withIDs(array($rule_id))
      ->executeOne();
    if (!$rule) {
      throw new PhutilArgumentUsageException(
        pht(
          'Unable to load Herald rule with ID or monogram "%s".',
          $rule_name));

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Pass the rule ID or monogram explicitly: bin/herald rule --rule H123 (or --rule 123).
2. In scripts, default and assert the variable first: RULE=${RULE:?"--rule is required"}.
3. Run 'bin/herald help rule' to see all flags before composing the command.

Example fix

# before
bin/herald rule --disable

# after
bin/herald rule --rule H123 --disable

$rule_name = $args->getArg('rule');
if (!strlen($rule_name)) {
  // print usage and exit non-zero BEFORE execute() proceeds
  throw new PhutilArgumentUsageException(pht(
    'Specify a rule to edit with "--rule <id|monogram>".'));
}

function hasRuleArgument(PhutilArgumentParser $args) {
  return strlen((string)$args->getArg('rule')) > 0;
}

try {
  (new HeraldRuleManagementWorkflow())->execute($args);
} catch (PhutilArgumentUsageException $ex) {
  // usage errors: print message, show help, exit code 2 — safe to retry
  fwrite(STDERR, $ex->getMessage()."\n");
  exit(2);
}

When it happens

Trigger: Running 'bin/herald rule' with no --rule flag at all, or with an empty value ('--rule ""). The strlen() check on getArg('rule') fires before any rule lookup happens.

Common situations: Copy-pasting the workflow invocation from docs that omit the flag; shell scripts where $RULE is unset and expands to nothing; assuming the tool is interactive and will prompt.

Related errors

• Use flags to specify at least one edit to apply to the rule
• Specify an object to test rules for with "--object".
• Specify a content type to run rules for. For this object, va
• Specify a commit to extract the diff from.
• Specify an atomizer class with %s.

AI-assisted analysis of phacility/phabricator@5720a38cfe (2026-08-21). Data as JSON: /api/errors/0a8e1719fea68dc9. Report an issue: GitHub.