CLI commands

Command names are consistent across brokers wherever the behaviour is shared. This page groups them by what they do rather than by binary, so the differences stand out.

Shared across every broker#

<broker> --version
<broker> version
<broker> doctor
<broker> doctor isolation
<broker> setup systemd [flags]
<broker> setup launchd [flags]
<broker> setup client [flags]
<broker> state check   --state-dir /absolute/state [--full]
<broker> state backup  --state-dir /absolute/state --output /absolute/new-backup
<broker> state restore --state-dir /absolute/state --backup /absolute/backup
<broker> state export  --state-dir /absolute/state --output /absolute/new-export.json

Doctor exit codes are 0 for OK, 1 for unsafe, 2 for inconclusive, and 64 for invalid arguments. State commands require the service to be stopped, because they acquire the state lease.

Common setup flags#

--user <name>                default: <broker>
--group <name>               default: <broker>
--config-dir <path>          default: /etc/<broker>
--state-dir <path>           default: /var/lib/<broker>
--systemd-dir <path>         default: /etc/systemd/system
--binary <path>              default: resolved current binary
--client <name>              required client identity
--operator <name>            required operator identity when the inbox is enabled
--shared-secret-file <path>  read the client secret from a file
--shared-secret-stdin        read the client secret from stdin
--operator-secret-file <path> preserve or rotate the operator credential
--endpoint <uri>             deployment-owned agent endpoint
--operator-endpoint <uri>    distinct deployment-owned operator endpoint
--agent-user <name>
--operator-user <name>
--telegram-bot-token-file <path>
--telegram-chat-id <id>
--dry-run
--no-start

Raw secret values are never accepted as command-line arguments.

Git-speaking brokers#

<broker> git install
<broker> git doctor
<broker> git status --json
<broker> git uninstall

hf-broker#

hf-broker                                  # run in the foreground
hf-broker mcp                              # stdio MCP server

hf-broker credential repair
hf-broker credential inspect --token-stdin --json
hf-broker credential status

hf-broker doctor policy \
  --profile /etc/hf-broker/policy-profile.json \
  --scope /etc/hf-broker/scope.json \
  --manifest /etc/hf-broker/policy-manifest.json

hf-broker client repo create   --target-json '…' --arguments-json '…'
hf-broker client repo delete   --target-json '…' --arguments-json '…'
hf-broker client bucket object list  --target-json '…' --arguments-json '…'
hf-broker client bucket object write --target-json '…' --arguments-json '…' --source ./file

hf-broker client operation wait <operation-id>

hf-broker client grant request <operation> <owner>/<name> [flags]
hf-broker client grant get    <grant-id>
hf-broker client grant wait   <grant-id>
hf-broker client grant cancel <grant-id>
hf-broker client grant revoke <grant-id>

Grant request flags include --type model|dataset|space, repeatable --ref and --path for repositories, repeatable --key for buckets, --minutes, --max-uses (a positive integer or unlimited), --reason, and --request-id.

Setup-specific flags: --hf-token-file, --xet-python, --repo owner/name, --repo-type model|dataset|space, repeatable --deny-operation <exact-name>, --replace-policy, and --reset-denied-operations.

gh-broker#

gh-broker mcp

gh-broker operations list --family pull_request
gh-broker operations describe repo.visibility.update

gh-broker operation submit <operation> \
  --target-json '…' \
  --arguments-json '…' \
  [--reason '…'] [--request-id '…'] [--wait]
gh-broker operation get    <id>
gh-broker operation wait   <id>
gh-broker operation cancel <id>

gh-broker doctor github --repo owner/name --agent-user agent-a --service-user gh-broker

gh-broker setup github-user enroll \
  --state-dir /var/lib/gh-broker \
  --credential-file ./user-credential.json \
  --github-app-client-id-file ./app-client-id \
  --github-app-client-secret-file ./app-client-secret
gh-broker setup github-user rotate [same flags]
gh-broker setup github-user revoke --user-id 1234 --state-dir /var/lib/gh-broker

Setup-specific flags: --github-app-id-file, --github-app-private-key-file, --github-app-client-id-file, --github-app-client-secret-file, --github-user-id, --github-webhook-secret-file, --scope-file, --git-endpoint, --dev-token-fallback, and --github-token-file.

doctor github accepts --env-file <path> for a nonstandard installation, or --env-file '' to use only the current process environment.

sudo-broker#

sudo-broker serve --admission-config /absolute/path

sudo-broker run <command-id> \
  --as <target-user> \
  --reason '…' \
  --operation-id <stable-id> \
  [--arg-json NAME=JSON]

sudo sudo-broker doctor host --agent agent-a

Setup-specific flags: --catalog-file and --policy-file.

The privileged helper sudo-broker-exec is installed in the adjacent libexec directory and is not invoked directly.

unyolo host command#

unyolo setup [--accessible] [--no-open]
unyolo setup status
unyolo setup --resume <session-id>

unyolo system profile lock          --profile /path/to/deployment
unyolo system profile lock --check  --profile /path/to/deployment

unyolo system validate --profile /path/to/deployment
unyolo system plan     --profile /path/to/deployment --output /tmp/plan.json
unyolo system apply    --profile /path/to/deployment \
  --expect-plan sha256:<digest> \
  --secret-file <slot>=/absolute/path
unyolo system verify   --profile /path/to/deployment
unyolo system export   --profile /path/to/deployment --json

unyolo system plan     --manifest manifest.json --signature manifest.sig --public-key release.pub
unyolo system install  --manifest manifest.json --signature manifest.sig --public-key release.pub
unyolo system upgrade  --manifest manifest.json --signature manifest.sig --public-key release.pub
unyolo system status [--json]
unyolo system doctor [--json]
unyolo system rollback

Run system commands through the root-owned worker the verified bootstrap installed at /opt/unyolo/bootstrap/v<version>/unyolo. Never run a user-local binary with sudo. The CLI refuses interactive root execution.

unyolo-telegram#

sudo unyolo-telegram setup systemd \
  --telegram-bot-token-file ./telegram-bot-token \
  --telegram-chat-id 123456789 \
  --hf-operator-token-file ./hf-operator-secret \
  --gh-operator-token-file ./gh-operator-secret \
  --sudo-operator-token-file ./sudo-operator-secret

Omit a provider token flag when that provider is not installed. Endpoint and group flags exist for non-default layouts.

Installer environment#

VERSION                     release tag, for example v0.1.0
INSTALL_DIR                 absolute writable install directory
UNYOLO_VERIFIER_FILE     absolute path to a separately verified verifier
UNYOLO_VERIFY_ONLY       download and verify without installing
UNYOLO_VERIFY_RELEASE_SET  verify every platform archive, the manifest, and the SBOM