What causes "Specify a private key with --private-key." in phacility/phabricator?

Generate (or locate) the device private key and pass it: bin/almanac register --device X --private-key /path/to/id_rsa.

phacility/phabricator · warning · PhutilArgumentUsageException

Specify a private key with --private-key.

Error message

Specify a private key with --private-key.

What it means

Usage exception from `bin/almanac register`: the --private-key flag is missing or empty. The workflow derives the corresponding public key on the fly with `ssh-keygen -y -f <tmp-copy>` and matches it against trusted device keys, so the private key file is required input for registration.

Source

Thrown at src/applications/almanac/management/AlmanacManagementRegisterWorkflow.php:74

    $raw_device = $device_name;
    if (strlen($identify_as)) {
      $raw_device = $identify_as;
    }

    $identity_device = id(new AlmanacDeviceQuery())
      ->setViewer($viewer)
      ->withNames(array($raw_device))
      ->executeOne();
    if (!$identity_device) {
      throw new PhutilArgumentUsageException(
        pht(
          'No such device "%s" exists!', $raw_device));
    }

    $private_key_path = $args->getArg('private-key');
    if (!strlen($private_key_path)) {
      throw new PhutilArgumentUsageException(
        pht('Specify a private key with --private-key.'));
    }

    if (!Filesystem::pathExists($private_key_path)) {
      throw new PhutilArgumentUsageException(
        pht('No private key exists at path "%s"!', $private_key_path));
    }

    $raw_private_key = Filesystem::readFile($private_key_path);

    $phd_user = PhabricatorEnv::getEnvConfig('phd.user');
    if (!$phd_user) {
      throw new PhutilArgumentUsageException(
        pht(
          'Config option "phd.user" is not set. You must set this option '.
          'so the private key can be stored with the correct permissions.'));
    }

View on GitHub (pinned to 5720a38cfe)

Solutions

Generate (or locate) the device private key and pass it: bin/almanac register --device X --private-key /path/to/id_rsa.
In scripts, verify the key path variable is set and non-empty before invoking the CLI.
Ensure the daemon/CLI user can read the key file; ssh-keygen refuses world-readable keys (the workflow copies it to a 0600 temp file, but the source must be readable).

Example fix

# before
$ bin/almanac register --device web-001
Usage Exception: Specify a private key with --private-key.

# after
$ ssh-keygen -t ed25519 -f /root/device.key -N ''
$ bin/almanac register --device web-001 --private-key /root/device.key

Defensive patterns

Strategy: validation

Validate before calling

: "${DEVICE_KEY_PATH:?device private key path required}"
[ -s "$DEVICE_KEY_PATH" ] || { echo "key missing: $DEVICE_KEY_PATH" >&2; exit 1; }
bin/almanac register --device "$ALMANAC_DEVICE" --private-key "$DEVICE_KEY_PATH"

Prevention

Generate the keypair in the same script step that registers, so the path is always populated.
Store key paths in one config var and reference it everywhere.
Check `bin/almanac register --help` when in doubt about flag names.

When it happens

Trigger: Running bin/almanac register --device web-001 without --private-key; an automation script passing an unexpanded variable like --private-key $KEY_PATH with KEY_PATH unset; using --key or --private_key flag names that do not exist.

Common situations: Provisioning scripts that generate the keypair at runtime but reference the path before generation completes; interactive use from memory; flag renamed/typo'd in copy-pasted runbooks.

Related errors

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