CLI reference

armadactl is the command-line tool for Armada. Use it to submit and watch jobs, manage queues, and ask the scheduler what it's doing.

Install armadactl

On a laptop install, Getting started installs armadactl into ~/bin for you.

Otherwise, use one of these:

The install script. From a clone of the Armada repository:

scripts/get-armadactl.sh

It downloads the latest release for your system and copies it into ~/bin. It says armadactl is now available on your PATH, but that change only lasts while the script runs: if armadactl isn't found afterwards, add ~/bin to your PATH (below).

A release download. Download the archive for your system from the Armada releases page (armadactl_<version>_darwin_all.tar.gz for any Mac, armadactl_<version>_linux_amd64.tar.gz or armadactl_<version>_linux_arm64.tar.gz for Linux, armadactl_<version>_windows_amd64.zip for Windows), then, on a Mac or Linux:

tar -xzf armadactl_*.tar.gz armadactl
mkdir -p ~/bin && mv armadactl ~/bin/

Check it works:

armadactl version

If you see command not found, add ~/bin to your PATH: export PATH="$HOME/bin:$PATH". To keep it for new terminals, add that line to ~/.zshrc (the macOS default) or ~/.bashrc.

Configure armadactl

armadactl reads ~/.armadactl.yaml. Each Armada installation is a named context:

currentContext: laptop
contexts:
  laptop:
    armadaUrl: localhost:30002
  prod:
    armadaUrl: armada.example.com:443
    openIdAuth:
      providerUrl: 'https://login.example.com/realms/armada'
      clientId: 'armada'
      localPort: 8085
      scopes: ['openid', 'profile', 'email']

An older config format, with armadaUrl at the top level and no contexts, still works but prints No context defined. This method of providing connection details will soon be deprecated. Move the settings into a context to stop the warning.

Options that work with every command:

Common tasks

# Submit jobs from a file, checking it first
armadactl submit job.yaml --dry-run
armadactl submit job.yaml

# Follow a job set (press Ctrl-C to stop)
armadactl watch my-team demo-1

# Cancel one job, or a whole job set
armadactl cancel job my-team demo-1 <job-id>
armadactl cancel job-set my-team demo-1

# Change the order of waiting jobs (lower runs first)
armadactl reprioritize job my-team demo-1 <job-id> 5
armadactl reprioritize job-set my-team demo-1 5

# Queues
armadactl create queue my-team --priority-factor 1
armadactl get queues
armadactl get queue my-team
armadactl delete queue my-team

# Why isn't my job running?
armadactl get job-report <job-id>
armadactl get queue-report my-team

Command reference

Every command has detailed help: armadactl <command> --help. For the full documentation in your terminal, run armadactl docs.

Jobs

Queues

Reports

get scheduling-report also accepts --job-id and --queue, but both are deprecated: they print This flag is deprecated and will be removed in a future release. Please use `job-report` instead. (or `queue-report`). Use get job-report and get queue-report instead.

A report for a job that's already running may say Most recent scheduling round that affected job <job-id>: none: reports only cover recent rounds.

Retry policies

Managing policies needs create_retry_policy, update_retry_policy or delete_retry_policy; anyone can read them.

Configuration and other commands

Worker clusters and nodes

These act on whole worker clusters (executors) or nodes, and are usually platform-team actions. The cancel and preempt commands only affect jobs already placed on that executor or node, and have no --dry-run. See Monitoring and fleet.

On a laptop install, the executor is Cluster1 and the worker node is armada-worker. The laptop grants cancel_any_jobs but not preempt_any_jobs or update_executor_settings.

Troubleshooting