phacility/phabricator · warning · PhutilArgumentUsageException

Specify a device with --device.

Error message

Specify a device with --device.

What it means

Usage exception from `bin/almanac register` (AlmanacManagementRegisterWorkflow): the --device flag was omitted or given an empty value. The register workflow installs a device identity (SSH keys) on a host and must know which Almanac device it is acting as, so the argument is mandatory before anything else runs.

Source

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

            'param' => 'name',
            'help' => pht(
              'Specify an alternate host identity. This is an advanced '.
              'feature which allows a pool of devices to share credentials.'),
          ),
          array(
            'name' => 'force',
            'help' => pht(
              'Register this host even if keys already exist on disk.'),
          ),
        ));
  }

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

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

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

    $identify_as = $args->getArg('identify-as');

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

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Pass the device name: bin/almanac register --device <device-name> --private-key <path>.
2. In scripts, fail early if the device variable is empty rather than invoking the CLI with a blank flag.
3. Confirm the exact device name with `bin/almanac device --name ...` or in the Almanac web UI; device names are case-sensitive namespace-normalized names.

Example fix

# before
$ bin/almanac register --private-key /root/id_device

# after
$ bin/almanac register --device web-001 --private-key /root/id_device

# shell provisioning guard
: "${ALMANAC_DEVICE:?ALMANAC_DEVICE must be set to the device name}"
bin/almanac register --device "$ALMANAC_DEVICE" --private-key "$KEY_PATH"

When it happens

Trigger: Running `bin/almanac register` with no flags; running `bin/almanac register --device ""` via a provisioning script where the device name variable is empty; typos like --devices=web1.

Common situations: Automated host provisioning where the device name comes from an unset environment variable or template placeholder; running the command from memory without checking `bin/almanac register --help`.

Related errors

• Specify a private key with --private-key.
• Config option "phd.user" is not set. You must set this optio
• Unable to change ownership of an identity file to daemon use
• This host already has a registered public key ("%s"). Remove
• This host already has a registered private key ("%s"). Remov

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