awaywork

Appearance

CLI reference ​

Every command's --help. The global --config option applies to all of them.

awaywork ​

text
Usage: awaywork [options] [command]

Run your coding agents on your real tasks, under rules you set

Options:
  -V, --version             output the version number
  -c, --config <path>       config file (default: $AWAYWORK_CONFIG or
                            ~/.config/awaywork/config.yml)
  -h, --help                display help for command

Commands:
  init [options]            set awaywork up with Claude Code's /away, or write
                            the detected defaults with --yes
  config                    print the config's path, what it says or its schema
  secret <name>             save a token to ~/.config/awaywork/env (mode 600),
                            from a hidden prompt or a pipe
  sources [options] [id]    list what a source's credentials can see
                            (workspaces, projects, teams, statuses), read-only;
                            with no id, every configured source
  plan [options]            show the next run's units in order, with each
                            provider's ceiling; runs no worker; browsable in a
                            terminal
  skip [options] [key]      leave an item (source:key, e.g. github:acme/api#5)
                            alone in the coming runs; with no key, list skipped
                            items
  unskip <key>              let awaywork pick up a skipped item (source:key)
                            again
  approve <key> [notes...]  approve the plan or result an item (source:key, e.g.
                            github:acme/api#5) waits on, replying approve on it
                            with the notes below
  skills                    list skills and eject built-ins to tweak
  run [options]             plan the units, start a worker per unit and publish
                            PRs and reports
  report [options] [id]     print a run's morning report, the latest by default;
                            browsable in a terminal
  watch                     keep running and start a run when a window opens;
                            `schedule install` keeps it running
  stats [options]           what each rule, skill and provider cost and
                            delivered across the runs kept
  replay <run> <unit>       re-run a past run's unit, its first step, on its
                            base commit and saved context with today's skills
                            and instructions; nothing is pushed
  schedule                  run awaywork when its windows open, on this machine,
                            in GitHub Actions or in a container
  doctor [options]          validate the config and check binaries, credentials,
                            quota and sources before a run
  help [command]            display help for command

awaywork init ​

text
Usage: awaywork init [options]

set awaywork up with Claude Code's /away, or write the detected defaults with
--yes

Options:
  -y, --yes             write the detected defaults, asking nothing; needs no
                        terminal
  --provider <id...>    with --yes: providers, first takes units first
  --source <id...>      with --yes: sources to take work from
  --window <start-end>  with --yes: the run window, e.g. 01:00-07:00
  --force               with --yes: replace an existing config
  -h, --help            display help for command

awaywork config ​

text
Usage: awaywork config [options] [command]

print the config's path, what it says or its schema

Options:
  -h, --help      display help for command

Commands:
  path            print the config file awaywork reads; exit 1 when it does not
                  exist
  explain         print what the config says as JSON, without reading a source
                  or a provider
  schema          print the config JSON Schema, for editor autocompletion
  help [command]  display help for command

awaywork config path ​

text
Usage: awaywork config path [options]

print the config file awaywork reads; exit 1 when it does not exist

Options:
  -h, --help  display help for command

awaywork config explain ​

text
Usage: awaywork config explain [options]

print what the config says as JSON, without reading a source or a provider

Options:
  -h, --help  display help for command

awaywork config schema ​

text
Usage: awaywork config schema [options]

print the config JSON Schema, for editor autocompletion

Options:
  -h, --help  display help for command

awaywork secret ​

text
Usage: awaywork secret [options] <name>

save a token to ~/.config/awaywork/env (mode 600), from a hidden prompt or a
pipe

Arguments:
  name        the variable, e.g. ASANA_TOKEN

Options:
  -h, --help  display help for command

awaywork sources ​

text
Usage: awaywork sources [options] [id]

list what a source's credentials can see (workspaces, projects, teams,
statuses), read-only; with no id, every configured source

Options:
  --json      print one object keyed by source id
  -h, --help  display help for command

awaywork plan ​

text
Usage: awaywork plan [options]

show the next run's units in order, with each provider's ceiling; runs no
worker; browsable in a terminal

Options:
  --json            print the plan, or with --rules the rules, and warnings as
                    JSON
  --repo <glob>     only units in repos matching owner/name, * globs
  --rule <n>        only units of this queue rule, counted from 1
  --rules           show what each rule takes now and what other rules take from
                    it, instead of the units; probes no provider
  --skipped [kind]  list the skipped items and why, or those of one kind
                    (choices: "no_rule", "skipped_by_you", "unchanged",
                    "over_cap", "waiting_for_review", "waiting_for_answer",
                    "waiting_for_approval", "approved", "invalid_plan",
                    "store_failed", "fanned_out", "waiting_for_task",
                    "task_merged", "task_done", "all_tasks_done", "gave_up",
                    "no_repo", "unlisted_repo", "invalid_branch",
                    "refused_delivery", "draft_moved", "continue_cap",
                    "continues_later", "running")
  --why <key>       say why an item is planned or skipped, by key, source:key or
                    the ref plan shows
  -h, --help        display help for command

awaywork skip ​

text
Usage: awaywork skip [options] [key]

leave an item (source:key, e.g. github:acme/api#5) alone in the coming runs;
with no key, list skipped items

Options:
  --until <date>   skip until this local date (YYYY-MM-DD) starts; default:
                   until unskip
  --reason <text>  why, shown by awaywork plan
  -h, --help       display help for command

awaywork unskip ​

text
Usage: awaywork unskip [options] <key>

let awaywork pick up a skipped item (source:key) again

Options:
  -h, --help  display help for command

awaywork approve ​

text
Usage: awaywork approve [options] <key> [notes...]

approve the plan or result an item (source:key, e.g. github:acme/api#5) waits
on, replying approve on it with the notes below

Options:
  -h, --help  display help for command

awaywork skills ​

text
Usage: awaywork skills [options] [command]

list skills and eject built-ins to tweak

Options:
  -h, --help      display help for command

Commands:
  list [options]  skills a rule can name, where each comes from and its delivery
                  default
  eject <name>    copy a built-in skill to skills/ beside the config, where it
                  shadows the built-in
  help [command]  display help for command

awaywork skills list ​

text
Usage: awaywork skills list [options]

skills a rule can name, where each comes from and its delivery default

Options:
  --json      print them as JSON, each with whether run --skill can pick it
  -h, --help  display help for command

awaywork skills eject ​

text
Usage: awaywork skills eject [options] <name>

copy a built-in skill to skills/ beside the config, where it shadows the
built-in

Options:
  -h, --help  display help for command

awaywork run ​

text
Usage: awaywork run [options]

plan the units, start a worker per unit and publish PRs and reports

Options:
  --dry-run       prepare each workspace (clone, context, prompt) but run no
                  worker
  --unit <id>     run only this unit, by id or item key
  --repo <glob>   run only units in repos matching owner/name, * globs
  --rule <n>      run only units of this queue rule, counted from 1
  --scheduled     run only inside a window and start no unit after it ends
  --detach        with --unit: return once the unit has started, leaving it
                  running
  --skill <name>  with --unit, on an item no rule takes: run this skill on it,
                  once
  -h, --help      display help for command

awaywork report ​

text
Usage: awaywork report [options] [id]

print a run's morning report, the latest by default; browsable in a terminal

Options:
  --list            list the last 20 runs: units, PRs and reports
  --json            print the run's results as JSON instead of the text
  --unit <n|key>    show one unit in full, by its number in the report, unit id
                    or item key
  --skipped [kind]  list the skipped items, or those of one kind (choices:
                    "no_rule", "skipped_by_you", "unchanged", "over_cap",
                    "waiting_for_review", "waiting_for_answer",
                    "waiting_for_approval", "approved", "invalid_plan",
                    "store_failed", "fanned_out", "waiting_for_task",
                    "task_merged", "task_done", "all_tasks_done", "gave_up",
                    "no_repo", "unlisted_repo", "invalid_branch",
                    "refused_delivery", "draft_moved", "continue_cap",
                    "continues_later", "running")
  -h, --help        display help for command

awaywork watch ​

text
Usage: awaywork watch [options]

keep running and start a run when a window opens; `schedule install` keeps it
running

Options:
  -h, --help  display help for command

awaywork stats ​

text
Usage: awaywork stats [options]

what each rule, skill and provider cost and delivered across the runs kept

Options:
  --json      print the totals as JSON
  -h, --help  display help for command

awaywork replay ​

text
Usage: awaywork replay [options] <run> <unit>

re-run a past run's unit, its first step, on its base commit and saved context
with today's skills and instructions; nothing is pushed

Options:
  -h, --help  display help for command

awaywork schedule ​

text
Usage: awaywork schedule [options] [command]

run awaywork when its windows open, on this machine, in GitHub Actions or in a
container

Options:
  -h, --help         display help for command

Commands:
  install [options]  keep `awaywork watch` running, which starts a run when a
                     window opens
  remove             remove the scheduled job, and
                     .github/workflows/awaywork.yml or the container's files in
                     the current repo
  status             show the installed scheduled job and what awaywork watch is
                     doing
  help [command]     display help for command

awaywork schedule install ​

text
Usage: awaywork schedule install [options]

keep `awaywork watch` running, which starts a run when a window opens

Options:
  --with <scheduler>  launchd, systemd, cron, github-actions, docker (default:
                      asks in a terminal, else launchd on macOS, else systemd if
                      it runs, else cron)
  -h, --help          display help for command

awaywork schedule remove ​

text
Usage: awaywork schedule remove [options]

remove the scheduled job, and .github/workflows/awaywork.yml or the container's
files in the current repo

Options:
  -h, --help  display help for command

awaywork schedule status ​

text
Usage: awaywork schedule status [options]

show the installed scheduled job and what awaywork watch is doing

Options:
  -h, --help  display help for command

awaywork doctor ​

text
Usage: awaywork doctor [options]

validate the config and check binaries, credentials, quota and sources before a
run

Options:
  --json      print the checks as a JSON array of { status, what, detail }
  -h, --help  display help for command