CLI reference
The workly binary is the server and the CLI. Install it with pip install "workly[cli]", or see the quickstart for the other ways. workly COMMAND --help prints the same help as this page.
The commands that call the API (queues, tasks, groups, workflows, schedules, runs, plan and deploy) connect to --url or WORKLY_URL, http://localhost:7337 by default, with --api-key or WORKLY_API_KEY. For hosted Workly, that is https://api.workly.run and a key from the console. They print a table, or the API’s JSON response with --json.
workly dev
Section titled “workly dev”Run a local development server (SQLite, no auth).
--config applies a workly.yaml once the server is listening, as workly deploy
would, so a fresh database starts with the file’s queues, workflows and
schedules rather than default settings. It’s applied each time the server
starts: restart it to apply changes to the file.
workly dev [flags]Flags:
--config string a workly.yaml to apply at startup, as workly deploy would--database-url string postgres:// or sqlite:// URL (env WORKLY_DATABASE_URL)--port int port to listen on (env WORKLY_PORT) (default 7337)workly serve
Section titled “workly serve”Run the Workly server (for self-hosting).
Requires WORKLY_DATABASE_URL (postgres://…) and WORKLY_SIGNING_SECRET. Other settings: WORKLY_API_KEY, WORKLY_PORT, WORKLY_METRICS_PORT, WORKLY_RETENTION, WORKLY_RUN_RETENTION, WORKLY_SHUTDOWN_TIMEOUT, WORKLY_SIGNING_SECRET_PREVIOUS, WORKLY_MCP and more; see https://github.com/worklydev/workly/blob/main/docs/configuration.md
workly serve [flags]Flags:
--database-url string postgres:// or sqlite:// URL (env WORKLY_DATABASE_URL)--port int port to listen on (env WORKLY_PORT) (default 7337)workly migrate
Section titled “workly migrate”Apply database migrations and exit.
workly migrate [flags]Flags:
--database-url string postgres:// or sqlite:// URL (env WORKLY_DATABASE_URL)--port int port to listen on (env WORKLY_PORT) (default 7337)workly healthcheck
Section titled “workly healthcheck”Exit 0 if the local server is ready (for Docker HEALTHCHECK).
workly healthcheck [flags]Flags:
--url string server URL (default http://localhost:$WORKLY_PORT)workly queues
Section titled “workly queues”List, configure, pause and resume queues.
Also: queue, q.
Flags for every workly queues command:
--api-key string API key (env WORKLY_API_KEY)--json print the API's JSON response--url string server URL (env WORKLY_URL, default http://localhost:7337)workly queues ls
Section titled “workly queues ls”List queues with their current work.
workly queues lsAlso: list.
workly queues get
Section titled “workly queues get”Show a queue’s configuration and current work.
workly queues get NAMEworkly queues put
Section titled “workly queues put”Create or update a queue.
Declarative, like the API: the queue ends up with exactly the settings given, and settings you leave out are reset to their defaults. Pausing is separate (see pause and resume).
workly queues put NAME [flags]Also: create, update.
Examples:
workly queues put emails --rate 50 --max-concurrency 10workly queues put webhooks --max-attempts 5 --timeout 10s --retry-on-4xxworkly queues put billing --auto-pause-after 20Flags:
--auto-pause-after int pause the queue by itself after this many 5xx, timeouts or network errors in a row, until a probe succeeds (default never)--backoff-multiplier float how fast the wait between retries grows (default 2)--max-attempts int total delivery attempts before a task fails (default 5)--max-backoff duration longest wait before a retry (default 1h0m0s)--max-concurrency int most deliveries in flight at once (default 3)--min-backoff duration shortest wait before a retry (default 2s)--rate float most deliveries started per second (default no limit)--retry-on-4xx retry 4xx responses (by default only 408 and 429 are retried)--timeout duration how long to wait for a response (default 30s)workly queues pause
Section titled “workly queues pause”Stop delivering a queue’s tasks (enqueueing still works).
workly queues pause NAMEworkly queues resume
Section titled “workly queues resume”Resume delivering a paused queue’s tasks.
workly queues resume NAMEworkly queues failures
Section titled “workly queues failures”Group a queue’s failed tasks by error, most common first.
workly queues failures NAMEworkly queues retry-failed
Section titled “workly queues retry-failed”Retry every failed task in a queue, e.g. after an endpoint outage.
workly queues retry-failed NAME [flags]Examples:
workly queues retry-failed emailsworkly queues retry-failed emails --error 'HTTP 503 Service Unavailable'Flags:
--error string only tasks whose last error is exactly this (see queues failures)workly queues cancel-pending
Section titled “workly queues cancel-pending”Cancel a queue’s pending tasks, including scheduled ones.
workly queues cancel-pending NAME [flags]Flags:
-y, --yes don't ask for confirmationworkly queues delete
Section titled “workly queues delete”Delete a queue and all its tasks.
workly queues delete NAME [flags]Also: rm.
Flags:
-y, --yes don't ask for confirmationworkly tasks
Section titled “workly tasks”Enqueue, inspect, retry and cancel tasks.
Also: task, t.
Flags for every workly tasks command:
--api-key string API key (env WORKLY_API_KEY)--json print the API's JSON response--url string server URL (env WORKLY_URL, default http://localhost:7337)workly tasks enqueue
Section titled “workly tasks enqueue”Enqueue a task to deliver to URL, and print its ID.
The queue is created with default settings if it doesn’t exist.
--payload and --body take a value, @file, or - for stdin.
workly tasks enqueue QUEUE URL [flags]Examples:
workly tasks enqueue emails https://api.example.com/send -d '{"user_id": 123}'workly tasks enqueue reports https://api.example.com/build --delay 10m -k report-2026-09cat event.json | workly tasks enqueue events https://api.example.com/ingest -d -Flags:
--at string deliver at this time (RFC 3339, e.g. 2026-10-01T09:00:00Z) --body string raw body: a value, @file, or - for stdin --content-type string content type of --body (default text/plain; charset=utf-8) --delay duration deliver after this delay, e.g. 30s or 2h --group string add the task to this open group (see workly groups)-H, --header stringArray header sent with every delivery, "Name: value" (repeatable)-k, --idempotency-key string don't enqueue if the queue already has a task with this key --max-attempts int override the queue's max attempts-X, --method string HTTP method (default POST) --on-complete string POST a summary of the task to this URL each time it finishes-d, --payload string JSON body: a value, @file, or - for stdin --timeout duration override the queue's response timeoutworkly tasks get
Section titled “workly tasks get”Show a task and its delivery attempts.
workly tasks get IDworkly tasks ls
Section titled “workly tasks ls”List tasks, newest first.
workly tasks ls [flags]Also: list.
Examples:
workly tasks ls --queue emails --state failedworkly tasks ls -k report-2026-09Flags:
--cursor string continue from a previous page --error string only tasks whose last error is exactly this (see queues failures) --group string only this group's tasks-k, --idempotency-key string only tasks with this idempotency key --limit int tasks per page (at most 200) (default 20) --queue string only this queue's tasks --state string only tasks in this state: pending, running, succeeded, failed or cancelledworkly tasks retry
Section titled “workly tasks retry”Deliver a task now; replays a finished task with fresh attempts.
workly tasks retry IDworkly tasks cancel
Section titled “workly tasks cancel”Cancel a pending or running task.
workly tasks cancel IDworkly groups
Section titled “workly groups”A task group tracks a set of tasks and enqueues a callback task once it is
closed and all of them have finished. Enqueue into a group with
workly tasks enqueue --group.
Also: group, g.
Flags for every workly groups command:
--api-key string API key (env WORKLY_API_KEY)--json print the API's JSON response--url string server URL (env WORKLY_URL, default http://localhost:7337)workly groups create
Section titled “workly groups create”Create an open group and print its ID.
workly groups create [flags]Examples:
group=$(workly groups create --name daily-prices --callback-url https://api.example.com/refresh)workly tasks enqueue prices https://api.example.com/price -d '{"symbol": "NET"}' --group $groupworkly groups close $groupFlags:
--callback-url string URL of the callback task, enqueued when the group completes-H, --header stringArray header sent with the callback, "Name: value" (repeatable)-k, --idempotency-key string return the existing group with this key instead of creating one --name string a label, e.g. the job this group is one run ofworkly groups get
Section titled “workly groups get”Show a group’s status and progress.
workly groups get IDworkly groups ls
Section titled “workly groups ls”List groups, newest first.
workly groups ls [flags]Also: list.
Flags:
--cursor string continue from a previous page--limit int groups per page (at most 200) (default 20)--name string only groups with this name--status string only groups in this status: open, running, succeeded or failedworkly groups close
Section titled “workly groups close”Stop a group accepting tasks, so it completes once they finish.
workly groups close IDworkly workflows
Section titled “workly workflows”A workflow runs HTTP steps in dependency order, each delivered as a task. A
step’s endpoint can hand its completion to a task group by answering with
Workly-Wait-For: group/
Also: workflow, wf.
Flags for every workly workflows command:
--api-key string API key (env WORKLY_API_KEY)--json print the API's JSON response--url string server URL (env WORKLY_URL, default http://localhost:7337)workly workflows ls
Section titled “workly workflows ls”List workflows and how each last ran.
workly workflows lsAlso: list.
workly workflows get
Section titled “workly workflows get”Show a workflow’s steps and their dependencies.
workly workflows get NAMEworkly workflows rm
Section titled “workly workflows rm”Delete a workflow’s definition; its runs are kept.
workly workflows rm NAME [flags]Flags:
-y, --yes delete without askingworkly workflows trigger
Section titled “workly workflows trigger”Start a run of a workflow and print its ID. --input is JSON passed to every
step without a body of its own; it takes a value, @file, or - for stdin.
workly workflows trigger NAME [flags]Also: start.
Examples:
workly workflows trigger daily-refresh --input '{"date": "2026-11-13"}'run=$(workly workflows trigger daily-refresh -k 2026-11-13) && workly workflows run $runFlags:
-k, --idempotency-key string return the existing run with this key instead of starting one-i, --input string JSON input for the run: a value, @file or - for stdinworkly workflows runs
Section titled “workly workflows runs”List workflow runs, newest first.
workly workflows runs [NAME] [flags]Flags:
--cursor string continue from a previous page--limit int runs per page (at most 200) (default 20)--status string only runs in this status: running, succeeded, failed or cancelledworkly workflows run
Section titled “workly workflows run”Show a workflow run: each step, and why it is where it is.
workly workflows run IDworkly workflows cancel
Section titled “workly workflows cancel”Cancel a workflow run: steps not yet started are skipped.
workly workflows cancel IDworkly workflows retry
Section titled “workly workflows retry”Reopen a failed or cancelled workflow run, under the definition it started with and with the same input. Steps that succeeded stay; the rest run again, each on its old task with a fresh set of attempts, and a step that was waiting for a group follows the group.
workly workflows retry IDworkly schedules
Section titled “workly schedules”Create, inspect, run and pause schedules.
A schedule calls a URL on a cron timetable. Each call is a run, with its own attempts and retries. Schedules are separate from queues and tasks.
Also: schedule, s.
Flags for every workly schedules command:
--api-key string API key (env WORKLY_API_KEY)--json print the API's JSON response--url string server URL (env WORKLY_URL, default http://localhost:7337)workly schedules ls
Section titled “workly schedules ls”List schedules with their next and last run.
workly schedules lsAlso: list.
workly schedules get
Section titled “workly schedules get”Show a schedule’s settings, next slots and recent runs.
workly schedules get NAMEworkly schedules put
Section titled “workly schedules put”Create or update a schedule that calls URL, or with --workflow (and no
URL) starts a run of that workflow, with --payload as the run’s input.
Declarative, like the API: the schedule ends up with exactly the settings
given, and settings you leave out are reset to their defaults. Pausing is
separate (see pause and resume). --payload and --body take a value, @file,
or - for stdin.
--cron takes five fields (minute hour day-of-month month day-of-week), or
@hourly, @daily, @weekly, @monthly or @yearly.
workly schedules put NAME [URL] [flags]Also: create, update.
Examples:
workly schedules put nightly-report https://api.example.com/reports/nightly \ --cron '0 3 * * *' --timezone Europe/Stockholm -d '{"kind": "daily"}'workly schedules put sync https://api.example.com/sync --cron '*/15 * * * mon-fri' --overlap allowworkly schedules put daily-refresh --workflow daily-refresh --cron '0 3 * * *'Flags:
--backoff-multiplier float how fast the wait between retries grows (default 2) --body string raw body: a value, @file, or - for stdin --content-type string content type of --body (default text/plain; charset=utf-8) --cron string when to run, e.g. '0 3 * * *' or @hourly (required)-H, --header stringArray header sent with every run, "Name: value" (repeatable) --max-attempts int total delivery attempts before a run fails (default 3) --max-backoff duration longest wait before a retry (default 5m0s)-X, --method string HTTP method (default POST) --min-backoff duration shortest wait before a retry (default 5s) --missed string slots missed while the server was down: skip, or catch_up (run the latest once) (default "skip") --on-complete string POST a summary of each run to this URL when it finishes --overlap string a slot that comes while the previous run is still going: skip or allow (default "skip")-d, --payload string JSON body: a value, @file, or - for stdin --retry-on-4xx retry 4xx responses (by default only 408 and 429 are retried) --timeout duration how long to wait for a response (default 30s) --timezone string IANA timezone the cron expression is read in, e.g. Europe/Stockholm (default "UTC") --workflow string start a run of this workflow instead of calling a URLworkly schedules pause
Section titled “workly schedules pause”Stop a schedule from running on its timetable.
workly schedules pause NAMEworkly schedules resume
Section titled “workly schedules resume”Resume a paused schedule from its next slot.
workly schedules resume NAMEworkly schedules trigger
Section titled “workly schedules trigger”Run a schedule now, outside its timetable, and print the run’s ID.
The run is delivered right away, even if the schedule is paused or a run is in flight. It doesn’t change when the schedule next runs.
workly schedules trigger NAMEAlso: run.
workly schedules delete
Section titled “workly schedules delete”Delete a schedule and all its runs.
workly schedules delete NAME [flags]Also: rm.
Flags:
-y, --yes don't ask for confirmationworkly runs
Section titled “workly runs”Inspect, retry and cancel schedule runs.
Also: run, r.
Flags for every workly runs command:
--api-key string API key (env WORKLY_API_KEY)--json print the API's JSON response--url string server URL (env WORKLY_URL, default http://localhost:7337)workly runs ls
Section titled “workly runs ls”List runs of every schedule, or of one, newest first.
workly runs ls [flags]Also: list.
Examples:
workly runs ls --state failedworkly runs ls --schedule nightly-reportFlags:
--cursor string continue from a previous page--limit int runs per page (at most 200) (default 20)--schedule string only this schedule's runs--state string only runs in this state: pending, running, succeeded, failed, cancelled or skippedworkly runs get
Section titled “workly runs get”Show a run and its delivery attempts.
workly runs get IDworkly runs retry
Section titled “workly runs retry”Deliver a run now; a finished or skipped run gets fresh attempts.
workly runs retry IDworkly runs cancel
Section titled “workly runs cancel”Cancel a pending or running run.
workly runs cancel IDworkly validate
Section titled “workly validate”Check workly.yaml, without contacting the server: its fields, cron expressions, timezones, URLs and headers, and that every ${NAME} it uses is set in the environment. It lists the ${NAME:-default} references that took their default.
workly validate [flags]Flags:
-f, --file string the configuration file (default "workly.yaml")workly plan
Section titled “workly plan”Show what workly deploy would change, without changing anything.
--format markdown writes the plan for a pull request comment or GitHub’s
step summary ($GITHUB_STEP_SUMMARY). --detailed-exitcode exits 0 when
there’s nothing to change, 2 when there are changes, and 3 when they
include deletes, so CI can ask for a closer look; errors exit 1.
workly plan [flags]Flags:
--api-key string API key (env WORKLY_API_KEY) --detailed-exitcode exit 2 when there are changes, 3 when they include deletes-f, --file string the configuration file (default "workly.yaml") --format string text, or markdown for a pull request or GitHub's step summary (default "text") --url string server URL (env WORKLY_URL, default http://localhost:7337)workly deploy
Section titled “workly deploy”Create and update the queues, workflows and schedules in workly.yaml, so
the server matches it. Shows the plan and asks first; --yes skips the
question, as CI needs. Running it again changes nothing. It never pauses or
resumes anything, and leaves what the file doesn’t declare alone, unless
the file sets prune: true: then it deletes the queues, workflows and
schedules a section of the file leaves out. Workflow runs already going
keep the definition they started with.
workly deploy [flags]Flags:
--api-key string API key (env WORKLY_API_KEY)-f, --file string the configuration file (default "workly.yaml") --url string server URL (env WORKLY_URL, default http://localhost:7337)-y, --yes apply without askingworkly version
Section titled “workly version”Print the version.
workly version