Program Options

The following options are supported:

• -h, --help show this help message and exit
• -v, --version show the program's version number and exit
• --license show the program's license and exit
• -p path, --project path (✅ New in >= 1.8) project configuration file, default: currently set project or None
• --dashboard-port port (✅ New in >= 1.8) port for the dashboard web interface, default: 8090
• --dashboard-host host (✅ New in >= 1.8) host address to bind the dashboard server to, default: 127.0.0.1
• --metrics-port port (✅ New in >= 1.8) port for the Prometheus metrics endpoint, default: 9090
• --metrics-host host (✅ New in >= 1.8) host address to bind the metrics server to, default: 127.0.0.1
• -r {on,off}, --recycle {on,off} turn on or off recycling of powered-off servers, either 'on' or 'off', default: on
• --end-of-life minutes number of minutes in an hour (60 minutes) period after which a recyclable server is considered to have reached its end of life and thus is deleted; default: 50
• -c path, --config path program configuration file
• --github-token GITHUB_TOKEN GitHub token, default: $GITHUB_TOKEN environment variable
• --github-repository GITHUB_REPOSITORY GitHub repository, default: $GITHUB_REPOSITORY environment variable
• --hetzner-token HETZNER_TOKEN Hetzner Cloud token, default: $HETZNER_TOKEN environment variable
• --ssh-key path public SSH key file, default: ~/.ssh/id_rsa.pub
• --default-type name default runner server type name, default: cx22
• --default-location name default runner server location name, default: not specified
• --default-image architecture:type:name_or_description default runner server image type and name or description, where the architecture is either: 'x86' or 'arm', and type is either: 'system','snapshot','backup','app', default: x86:system:ubuntu-22.04
• -m count, --max-runners count maximum number of active runners, default: 10
• --delete-random delete random recyclable server when the maximum number of servers is reached, by default, server prices are used
• --max-runners-in-workflow-run count maximum number of runners allowed to be created for a single workflow run, default: not set
• --with-label label --with-label ... only create runners for jobs that have the specified label, default: self-hosted
• --label-prefix prefix support type, image, and location job labels with the specified prefix
• --meta-label name label,... --max-label name label,... (✅ New in >= 1.6) runner meta label that will be expanded to a list of given labels
• -w count, --workers count number of concurrent workers, default: 10
• --scripts path (✅ New in >= 1.6) path to the folder that contains custom server scripts
• ❌ Deprecated in >= 1.6, use --scripts instead
  • --setup-script path path to the custom server setup script
• ❌ Deprecated in >= 1.6, use --scripts instead
  • --startup-x64-script path path to the custom server startup script
• ❌ Deprecated in >= 1.6, use --scripts instead
  • --startup-arm64-script path path to the custom ARM64 server startup script
• --max-powered-off-time sec maximum time after which a powered-off server is deleted, default: 60 sec
• --max-unused-runner-time sec maximum time after which an unused runner is removed and its server deleted, default: 180 sec
• --max-runner-registration-time maximum time after which the server will be deleted if its runner is not registered with GitHub, default: 180 sec
• --max-server-ready-time sec maximum time to wait for the server to be in the running state, default: 180 sec
• --scale-up-interval sec scale-up service interval, default: 15 sec
• --scale-down-interval sec scale-down service interval, default: 15 sec
• --debug enable debugging mode, default: False
• commands:
  • command
    • dashboard (✅ New in >= 1.8) open dashboard in web browser
    • delete delete all servers
    • list list all servers
    • ssh ssh to a server
    • estimate (✅ New in >= 1.7) cost estimator commands
      • -o path, --output path save estimate into the given file using the YAML format
      • --ipv4 price IPv4 price per hour, default: 0.0008
      • --ipv6 price IPv6 price per hour, default: 0.0000
      • run run cost estimator
        • id run id
        • --attempt number attempt number
      • job job cost estimator
        • id job id
      • runs runs cost estimator
        • --actor name actor name
        • --branch name branch name
        • --event name event name
        • --status {queued,in_progress,completed,success,failure,neutral,cancelled,skipped,timed_out,action_required} status value
        • --exclude-pull-requests exclude pull requests
        • --head-sha value head SHA value
    • cloud cloud service commands
      • -n server, --name server deployment server name, default: github-hetzner-runners
      • --host host (✅ New in >= 1.8) host (IP or hostname) of the cloud service server to connect to directly via SSH, bypassing IP lookup by name using the Hetzner API
      • deploy deploy cloud service
        • -f, --force force deployment if it already exists
        • --version number|latest service package version to deploy, either a version number or 'latest', default: current package version
        • -l name, --location name deployment server location, default: ash
        • -t name, --type name deployment server type, default: cpx11
        • -i architecture:type:name_or_description, --image architecture:type:name_or_description deployment server image type and name or description, where the architecture is either: 'x86' or 'arm', and the type is either: 'system','snapshot','backup','app', default: x86:system:ubuntu-22.04
        • --setup-script path path to custom deployment server setup script
      • redeploy redeploy on the same cloud service server
        • --version number|latest service package version to deploy, either a version number or 'latest', default: current package version
      • log get cloud service log
        • -c name[:width][,...], --columns name[:width][,...] comma separated list of columns to include and their optional width
        • --raw output raw log
        • -f, --follow follow log journal, default: False
        • -n [+]number, --lines [+]number output the last number of lines, with --follow the default is 10, use '+' before the number to output the log, starting with the line number
        • command
          • delete delete log
      • status get cloud service status
      • start start cloud service
      • stop stop cloud service
      • install install cloud service
        • -f, --force force installation if service already exists
      • uninstall uninstall cloud service
      • upgrade upgrade cloud service
        • --version version package version, default: the latest
      • ssh ssh to cloud service
        • command print ssh command to cloud service
      • dashboard (✅ New in >= 1.8) open dashboard through SSH tunnel to cloud service
        • --local-port port local port for SSH tunnel, default: 7090
        • --remote-port port remote dashboard port, default: --dashboard-port
        • --timeout seconds timeout for establishing SSH tunnel, default: 30 seconds
    • service service commands
      • install install service
        • -f, --force force installation if service already exists
      • uninstall uninstall service
      • status get service status
      • log get service log
        • -c name[:width][,...], --columns name[:width][,...] comma separated list of columns to include and their optional width
        • -f, --follow follow log journal, default: False
        • -n [+]number, --lines [+]number output the last number of lines, with --follow the default is 10, use '+' before the number to output the log, starting with the line number
        • --raw output raw log
        • command
          • format format log
          • delete delete log
      • start start service
      • stop stop service
    • images (✅ New in >= 1.7.241002) images commands
      • list list images
        • --name name can be used to filter images by their name
        • --label selector can be used to filter servers by labels
        • --bound-to id server id linked to the image. Only available for images of type backup
        • --type type choices: 'system', 'snapshot', 'backup', 'app'
        • --arch architecture choices: 'x86' or 'arm'
        • --status status can be used to filter images by their status
        • --sort sort sort by 'id', 'name', 'created', you can add one of ':asc', ':desc' to modify sort order, ':asc' is default
        • --include-deprecated include deprecated images in the response, default: False
      • delete delete image
        • --id id image id
      • create create snapshot
        • -n name, --name name snapshot name (required)
        • --setup-script path path to custom setup script that will be executed on the server to customize the default image (required)
        • -l name, --location name server location
        • -t name, --type name server type, default: cpx11
        • -i architecture:type:name_or_description, --image architecture:type:name_or_description base server image type and name or description, where the architecture is either: 'x86' or 'arm', the type is either: 'system','snapshot','backup','app', followed by the name, default: x86:system:ubuntu-22.04
        • --server-name name server name, default: snapshot-server
    • projects (✅ New in >= 1.8) project management commands
      • list list all projects
        • --show-tokens show full tokens instead of masking them
      • add add a new project
        • name project name (required)
        • --hetzner-token token Hetzner Cloud token
        • --github-token token GitHub token
        • --github-repository repository GitHub repository
        • --config path configuration file
      • update update a project
        • name project name (required)
        • --hetzner-token token Hetzner Cloud token
        • --github-token token GitHub token
        • --github-repository repository GitHub repository
        • --config path configuration file
      • delete delete a project
        • name project name (required)
      • set set current project
        • name project name (required)
      • unset unset current project