jobs

Background Jobs

Manage background shell commands: $ARGUMENTS

Commands

Command	Description
aux4 jobs run "<command>"	Run a command in the background, returns job JSON
aux4 jobs list	List all jobs
aux4 jobs list --state RUNNING	List jobs filtered by state
aux4 jobs status "<id>"	Show job status, exit code, duration
aux4 jobs output "<id>"	Print captured stdout
aux4 jobs output "<id>" --stream stderr	Print captured stderr
aux4 jobs kill "<id>"	Kill a running job
aux4 jobs killall	Kill all running jobs
aux4 jobs on "<id>" --success "<cmd>" --failure "<cmd>" --complete "<cmd>"	Register callbacks

Job States

State	Meaning
RUNNING	Job is currently executing
COMPLETED	Job finished with exit code 0
FAILED	Job finished with non-zero exit code
KILLED	Job was manually killed

Callback Environment Variables

When callbacks fire, these variables are available:

• AUX4_JOB_ID — Job ID
• AUX4_JOB_STATE — Final state
• AUX4_JOB_EXIT_CODE — Exit code
• AUX4_JOB_COMMAND — Original command
• AUX4_JOB_DIR — Working directory

When to Use Jobs

Use aux4 jobs run proactively for:

• Long-running builds — aux4 jobs run "npm run build"
• Deployments — aux4 jobs run "kubectl apply -f deploy.yaml"
• Data processing — aux4 jobs run "python process.py --input data.csv"
• Tests — aux4 jobs run "aux4 test run"
• Any command that takes more than a few seconds

Patterns

Fire and check later

aux4 jobs run "npm run build"
# ... do other work ...
aux4 jobs status "<id>"
aux4 jobs output "<id>"

Run with callbacks

aux4 jobs run "deploy.sh" --onSuccess "echo deployed" --onFailure "echo FAILED"

Combine with polling

aux4 jobs run "terraform apply -auto-approve"
aux4 poll --command "aux4 jobs status <id> | grep state" --expectation "*COMPLETED*" --interval 10 --maxWait 300

Rules

• Use jobs for anything long-running — don't block the conversation
• Check job status before reporting results
• Read job output to verify success, not just the exit code
• Kill stale jobs when they're no longer needed