phacility/phabricator · error · PhutilArgumentUsageException

Use "--output <path>" to specify an output file, or "--outpu

Error message

Use "--output <path>" to specify an output file, or "--output -" to print to stdout.

What it means

Phabricator's bulk export workflow (bin/bulk export) refuses to run when no --output destination was supplied. Every export must state where results go: a file path, or the special value '-' to stream to stdout. This is a PhutilArgumentUsageException, so the command prints the message and exits nonzero before executing any query, preventing an expensive export from silently going nowhere.

Source

Thrown at src/applications/transactions/bulk/management/PhabricatorBulkManagementExportWorkflow.php:81

      throw new PhutilArgumentUsageException(
        pht(
          'Unknown export format ("%s"). Known formats are: %s.',
          $format_key,
          implode(', ', array_keys($all_formats))));
    }

    if (!$format->isExportFormatEnabled()) {
      throw new PhutilArgumentUsageException(
        pht(
          'Export format ("%s") is not enabled.',
          $format_key));
    }

    $is_overwrite = $args->getArg('overwrite');
    $output_path = $args->getArg('output');

    if (!strlen($output_path)) {
      throw new PhutilArgumentUsageException(
        pht(
          'Use "--output <path>" to specify an output file, or "--output -" '.
          'to print to stdout.'));
    }

    if ($output_path === '-') {
      $is_stdout = true;
    } else {
      $is_stdout = false;
    }

    if ($is_stdout && $is_overwrite) {
      throw new PhutilArgumentUsageException(
        pht(
          'Flag "--overwrite" has no effect when outputting to stdout.'));
    }

    if (!$is_overwrite) {

View on GitHub (pinned to 5720a38cfe)

Solutions

Add --output <path> to write the export to a file (e.g. --output /tmp/tasks.csv).
Add --output - to print the export to stdout, useful for piping into another command.
Run `bin/bulk help export` to confirm the exact argument names before scripting it.

Example fix

# before
bin/bulk export --format csv --query all
# after
bin/bulk export --format csv --query all --output -

Defensive patterns

Strategy: validation

Validate before calling

# shell wrapper: refuse to run an export with no --output
case " $* " in
  *' --output '*) ;;
  *) echo 'refusing to export: --output is required' >&2; exit 2 ;;
esac
bin/bulk export "$@"

Try / catch

PHP harness: catch PhutilArgumentUsageException around the workflow execute() and map it to a distinct exit code (e.g. 64/EX_USAGE) so pipelines can separate bad invocation from runtime failure.

Prevention

Always pass --output explicitly, even for stdout ('--output -').
Script wrappers should validate required flags before invoking the CLI.
Treat any nonzero exit from bin/bulk as a failed invocation and surface stderr in CI logs.

When it happens

Trigger: Invoking `bin/bulk export` with --format and --query but no --output flag. The check is `!strlen($args->getArg('output'))`, so both a completely absent flag and an explicitly empty string trigger it.

Common situations: Cron/backup scripts written against an older CLI that defaulted to stdout; copy-pasting an export command from docs that omit --output; interactive use where the user expects a destination prompt.

Related errors

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