Nomad Cheatsheet

nomad.sh

# Nomad CLI Cheatsheet (Detailed)

# General Syntax: nomad <command> [subcommand] [options] [args]

# --- Common Global Options ---
# -address=<ADDR>     Nomad server address (env: NOMAD_ADDR)
# -namespace=<NS>     Target namespace (env: NOMAD_NAMESPACE, default: "default")
# -region=<REGION>    Target region (env: NOMAD_REGION)
# -token=<TOKEN>      ACL token for request (env: NOMAD_TOKEN)
# -ca-cert=<PATH>     Path to CA cert file for TLS
# -client-cert=<PATH> Path to client cert file for TLS
# -client-key=<PATH>  Path to client key file for TLS
# -tls-skip-verify    Disable TLS host verification (INSECURE)
# -json               Output in JSON format
# -t | -template=<GO_TPL> Format output using Go template
# -verbose | -v       Verbose output
# -h | -help          Help for any command/subcommand

# --- Job Management ---
nomad job run <JOB_FILE.nomad>             # Run a new job or update an existing one
nomad job run -detach <JOB_FILE.nomad>     # Run and don't wait for deployment to complete
nomad job run -check-index <IDX> <JOB_FILE> # Run only if ModifyIndex matches <IDX> (optimistic concurrency)
nomad job run -var="key=value" <JOB_FILE>  # Pass variables to the job
nomad job run -var-file="vars.tfvars" <JOB_FILE> # Pass variables from a file
nomad job plan <JOB_FILE.nomad>            # Dry-run, show changes without applying
nomad job plan -diff <JOB_FILE.nomad>      # Show a detailed diff of changes
nomad job status <JOB_ID_OR_PREFIX>        # Status of a job and its allocations
nomad job status -verbose <JOB_ID>         # Detailed status including events
nomad job status                           # Status of all jobs in the namespace
nomad job inspect <JOB_ID_OR_PREFIX>       # Show job definition as submitted (effective spec)
nomad job stop <JOB_ID_OR_PREFIX>          # Stop a job (sends SIGINT, then SIGKILL)
nomad job stop -purge <JOB_ID_OR_PREFIX>   # Stop and purge job (remove from listings)
nomad job stop -detach <JOB_ID>            # Stop and don't wait
nomad job stop -no-shutdown-delay <JOB_ID> # Stop without shutdown delay (Nomad 1.4+)
nomad job logs <JOB_ID_OR_PREFIX>          # Logs for all allocations of a job (stdout)
nomad job logs -f <JOB_ID_OR_PREFIX>       # Follow/tail logs
nomad job logs -stderr <JOB_ID_OR_PREFIX>  # Show only stderr
nomad job logs -task <TASK_NAME> <JOB_ID>  # Logs for a specific task group within the job
nomad job dispatch <JOB_ID_OR_PREFIX>      # Dispatch a parameterized or batch job
nomad job dispatch -meta "key=value" <JOB_ID> # Dispatch with meta parameters
nomad job dispatch -payload <PAYLOAD_FILE> <JOB_ID> # Dispatch with payload from file
nomad job revert <JOB_ID> <TARGET_VERSION> # Revert job to a previous version
nomad job history <JOB_ID_OR_PREFIX>       # Show job version history
nomad job scale <JOB_ID> <TASK_GROUP_NAME> <COUNT> # Scale a task group (Nomad 1.3+)
nomad job scale -status <JOB_ID> <TG_NAME> # Get current scale status
nomad job validate <JOB_FILE.nomad>        # Validate job file syntax locally
nomad job fmt <PATH_TO_JOB_OR_DIR>         # Format job files to HCL2 canonical format
nomad job allocs <JOB_ID_OR_PREFIX>        # List allocations for a specific job
nomad job deployments <JOB_ID_OR_PREFIX>   # List deployments for a specific job

# --- Allocation Management ---
nomad alloc status <ALLOC_ID_OR_PREFIX>    # Status of a specific allocation
nomad alloc status                         # Status of all allocations (can be filtered by job/node)
nomad alloc inspect <ALLOC_ID_OR_PREFIX>   # Inspect an allocation, shows details and events
nomad alloc logs <ALLOC_ID_OR_PREFIX>      # Logs for all tasks in an allocation
nomad alloc logs -f <ALLOC_ID_OR_PREFIX>   # Follow logs for an allocation
nomad alloc logs <ALLOC_ID> <TASK_NAME>    # Logs for a specific task in an allocation
nomad alloc fs <ALLOC_ID_OR_PREFIX> [PATH] # List files or cat file content in an alloc's sandbox
  nomad alloc fs <ALLOC_ID> ls /alloc/logs/ # List files in logs directory
  nomad alloc fs <ALLOC_ID> cat /alloc/data/my_file.txt # Cat a file
  nomad alloc fs -G <ALLOC_ID> stat /alloc/data/my_file.txt # Stat a file (like `ls -l`)
nomad alloc exec [-i -t] <ALLOC_ID> <COMMAND> [ARGS...] # Execute command in allocation's default task
nomad alloc exec -i -t -task <TASK_NAME> <ALLOC_ID> /bin/sh # Interactive shell in specific task
nomad alloc restart <ALLOC_ID_OR_PREFIX>   # Restart all tasks in an allocation
nomad alloc signal [-s SIGKILL] <ALLOC_ID> <TASK_NAME> # Send signal to a task in an alloc (default SIGTERM)
nomad alloc stop <ALLOC_ID_OR_PREFIX>      # Stop an allocation (useful for system/sysbatch jobs)

# --- Node / Client Management ---
nomad node status                          # Status of all client nodes
nomad node status <NODE_ID_OR_PREFIX>      # Status of a specific node
nomad node status -verbose <NODE_ID>       # Detailed status including resources and events
nomad node drain -enable <NODE_ID_OR_PREFIX> # Drain a node (prevent new allocs, migrate existing)
nomad node drain -enable -deadline=5m <NODE_ID> # Drain with a deadline
nomad node drain -enable -ignore-system <NODE_ID> # Drain, don't migrate system jobs
nomad node drain -disable <NODE_ID_OR_PREFIX> # Undrain a node, make it eligible again
nomad node eligibility -enable <NODE_ID>   # Enable scheduling eligibility for a node
nomad node eligibility -disable <NODE_ID>  # Disable scheduling eligibility for a node
nomad node allocs <NODE_ID_OR_PREFIX>      # List allocations running on a specific node

# --- Server / Cluster Management ---
nomad server members                       # List server members, status, protocol version
nomad operator raft list-peers             # Show Raft peers, leader, last index
nomad operator raft remove-peer -address <IP:PORT_OR_ID> # Remove a dead server (USE WITH CAUTION)
nomad operator raft autopilot get-config   # View Autopilot configuration
nomad operator raft autopilot set-config [OPTS] # Configure Autopilot (e.g., -cleanup-dead-servers)
nomad operator raft autopilot state        # View Autopilot health state
nomad operator scheduler get-config        # View current scheduler configuration
nomad operator scheduler set-config [OPTS] # Modify scheduler config (e.g., -memory-oversubscription-enabled)
nomad system gc                            # Force server-side garbage collection (jobs, nodes, evals)


# --- Deployments (Managing Job Updates) ---
nomad deployment list                      # List active deployments
nomad deployment status <DEPLOY_ID_OR_PREFIX> # Status of a specific deployment
nomad deployment promote <DEPLOY_ID_OR_PREFIX> # Promote a canary deployment or unblock a paused one
nomad deployment promote -all <DEPLOY_ID>  # Promote all canaries at once
nomad deployment fail <DEPLOY_ID_OR_PREFIX> # Mark a deployment as failed, triggers rollback
nomad deployment pause <DEPLOY_ID_OR_PREFIX> # Pause an in-progress deployment
nomad deployment resume <DEPLOY_ID_OR_PREFIX> # Resume a paused deployment
nomad deployment unblock <DEPLOY_ID_OR_PREFIX> # Unblock a deployment that failed due to unhealthy allocs

# --- Variables (Nomad Enterprise or OSS with compatible plugins) ---
nomad var list [PREFIX_PATH]               # List variables, optionally filtered by prefix
nomad var get <VAR_PATH>                   # Get a variable's value
nomad var get -version=<N> <VAR_PATH>      # Get a specific version of a variable
nomad var put <VAR_PATH>=<VALUE>           # Set/update a variable
nomad var put <VAR_PATH>@<FILE_PATH>       # Set/update a variable from file content
nomad var delete <VAR_PATH>                # Delete a variable

# --- ACL Management ---
nomad acl bootstrap                        # Bootstrap ACL system (first time setup)
nomad acl policy list                      # List ACL policies
nomad acl policy inspect <POLICY_NAME>     # Inspect an ACL policy
nomad acl policy apply <POLICY_NAME> <POLICY_FILE.hcl> # Create/update an ACL policy
nomad acl policy delete <POLICY_NAME>      # Delete an ACL policy
nomad acl role list                        # List ACL roles
nomad acl role inspect <ROLE_NAME>         # Inspect an ACL role
nomad acl role create -name=<NAME> -policy=<POLICY_NAME> # Create an ACL role
nomad acl role delete <ROLE_NAME>          # Delete an ACL role
nomad acl token list                       # List ACL tokens (requires management token)
nomad acl token self                       # Display current token's properties
nomad acl token create -name=<NAME> -role=<ROLE_NAME> # Create an ACL token
nomad acl token delete <ACCESSOR_ID>       # Delete an ACL token

# --- Volume Management (CSI) ---
nomad volume create <VOLUME_SPEC_FILE.hcl> # Create a new volume
nomad volume list                          # List all volumes
nomad volume status <VOLUME_ID_OR_PREFIX>  # Status of a specific volume
nomad volume inspect <VOLUME_ID_OR_PREFIX> # Inspect a volume's details
nomad volume delete <VOLUME_ID_OR_PREFIX>  # Delete a volume (must be detached)
nomad volume detach <VOLUME_ID> <NODE_ID>  # Detach volume from a node (for maintenance)

# --- Namespace Management ---
nomad namespace list                       # List all namespaces
nomad namespace inspect <NAMESPACE_NAME>   # Inspect a namespace's details
nomad namespace apply <NAMESPACE_FILE.hcl> # Create or update a namespace
nomad namespace delete <NAMESPACE_NAME>    # Delete a namespace (must be empty)

# --- Other Useful Commands ---
nomad ui [-address <ADDR>]                 # Open Nomad Web UI in browser (default: localhost:4646)
nomad version                              # Show Nomad CLI and Server version (if connected)
nomad agent-info                           # Display information about the local Nomad agent (if running)

# --- Tips & Aliases (example for .bashrc/.zshrc) ---
# alias n='nomad'
# alias njr='nomad job run'
# alias njs='nomad job status'
# alias nji='nomad job inspect'
# alias njl='nomad job logs -f'
# alias nas='nomad alloc status'
# alias nal='nomad alloc logs -f'
# alias nae='nomad alloc exec -i -t'
# alias nns='nomad node status'
# alias nd='nomad deployment'