CLI reference (conveyor)

conveyor is the command-line client for a Conveyor server. It is two things in one binary:

• a producer: enqueue tasks (enqueue, enqueue-tx), and
• an operator console: inspect and drive the system (queues, tasks, limits, cron, cluster, and the live event stream).

Operating the system lives here and in the dashboard, deliberately kept out of the SDKs: the SDKs are the produce-and-consume surface for application code, while rescheduling, running, canceling, pausing, limiting, and cron management are operator actions. See the operations guide for the wider deployment picture.

The CLI talks to a running conveyord. It does not start a server. To run one, see the operations guide; for an in-process server, see embedded mode.

Installing

Build it from the repository:

go build -o conveyor ./cmd/conveyor

Or run it without installing:

go run ./cmd/conveyor <command> [flags]

Connecting: global flags and environment

Every command accepts these, and the same two settings cover the whole session:

Setting	Flag	Environment	Default
Server URL	--addr	CONVEYOR_ADDR	http://localhost:8080
Bearer token	--token	CONVEYOR_TOKEN	empty (dev servers only)
Output format	--output / -o	none	table

A flag wins over its environment variable. Outside --dev, a server requires a token, so set --token/CONVEYOR_TOKEN. When the server runs with api.read_only, the mutating commands return permission denied while reads, enqueue, and the event stream still work.

--output json renders the listing and inspection commands (stats, tasks get, tasks list, ratelimit ls, concurrency ls, group ls, cron list, cluster info, cluster sessions, broker info, webhooks list, and the task actions) as JSON for scripting; the default table is human-readable.

The JSON is the wire response, so it follows the protobuf JSON mapping: fields are present at their zero value rather than omitted, an empty listing is an empty array, and 64-bit integers are rendered as strings ("pending": "12"), which matters if you do arithmetic on them.

export CONVEYOR_ADDR=https://conveyor.internal:8080
export CONVEYOR_TOKEN=$(cat /run/secrets/conveyor-token)

conveyor stats

Command overview

Command	Purpose
enqueue	Commit one task
enqueue-tx	Commit many tasks atomically (all-or-nothing)
tasks	Inspect and operate on tasks (get, list, run, cancel, delete, archive, reschedule)
stats	Per-queue state counts and pause flags
queues	Pause and resume queues
ratelimit	Per-queue dispatch rate limits (set, rm, ls)
concurrency	Per-queue per-key concurrency limits (set, rm, ls)
group	Per-group aggregation overrides (set, rm, ls)
cron	Cron entries (add, list, pause, resume, delete)
webhooks	Webhook worker registrations (add, list, pause, resume, delete)
cluster	Cluster membership and worker sessions (info, sessions)
broker	Storage backend inspection (info)
events	Stream task lifecycle events until interrupted
completion	Generate a shell autocompletion script

Run conveyor <command> --help (or conveyor <command> <subcommand> --help) for the authoritative, version-matched flags.

Producing work

enqueue: commit one task

conveyor enqueue <type> [flags]

<type> is the handler routing key. The payload is JSON passed with --json.

Flag	Meaning
--queue	Target queue (server default when empty)
--json	JSON payload
--id	Client-assigned task id for idempotent retries
--in	Delay execution by a duration, e.g. 5m
--at	Delay execution until an RFC3339 time
--expires-in	Archive the task if not dispatched within this duration
--expires-at	Archive the task if not dispatched by this RFC3339 time
--max-retry	Retry budget (server default when 0)
--priority	Dispatch priority 1..9 (server default when 0)
--retention	Keep the completed task visible for this long
--unique	Reject duplicates of this task for the given TTL
--unique-key	Explicit uniqueness key (default: type + payload hash)
--retry-strategy	Retry backoff: exponential, linear, or fixed
--retry-base	First-retry delay ceiling
--retry-max	Overall retry delay cap
--encryption-key	Seal the payload with AES-256-GCM, as <id>:<base64-secret> (default CONVEYOR_ENCRYPTION_KEY)

conveyor enqueue email:welcome --queue critical --json '{"user_id":42}' --in 5m

enqueue-tx: commit many tasks atomically

conveyor enqueue-tx --file <path> [--encryption-key <id>:<secret>]

enqueue-tx commits a set of tasks all-or-nothing: either every task is enqueued or none is. If any task fails (a duplicate unique key, a unique-key collision between two tasks in the file, or an invalid task), nothing is committed. This is atomic multi-task enqueue, distinct from the best-effort behavior a per-task loop of enqueue would give. The tasks may span queues, priorities, and schedules.

--file is a JSON array of task specs. Each spec mirrors the enqueue flags:

Field	Maps to	Notes
type	<type>	Required
queue	--queue
json	--json	A JSON value used as the payload
id	--id
in	--in	Duration string, e.g. "5m"
at	--at	RFC3339 time
expires_in	--expires-in	Duration string
expires_at	--expires-at	RFC3339 time
max_retry	--max-retry
priority	--priority
retention	--retention	Duration string
unique	--unique	Duration string
unique_key	--unique-key

// tasks.json
[
  {"type": "order:charge",  "queue": "billing", "json": {"id": "order-42"}, "priority": 7},
  {"type": "email:receipt", "queue": "mail",    "json": {"id": "order-42"}},
  {"type": "ledger:post",                        "json": {"id": "order-42"}}
]

conveyor enqueue-tx --file tasks.json

--encryption-key seals every payload in the file before it leaves the CLI, the same as enqueue. For the model behind this, see end-to-end encryption.

Inspecting

stats

conveyor stats

Prints each queue with its per-state counts (scheduled, pending, active, retry, completed, archived, aggregating, blocked) and pause flag.

tasks get / tasks list

conveyor tasks get <id>
conveyor tasks list [--queue NAME] [--state STATE] [--limit N]

tasks list shows tasks newest first. --state is one of scheduled, pending, active, retry, completed, archived, canceled.

conveyor tasks list --state retry --queue critical --limit 50

cluster info / cluster sessions

conveyor cluster info
conveyor cluster sessions

cluster info reports the nodes in the cluster (a debugging aid; a single-node server reports one node). cluster sessions lists the worker sessions connected to the reachable node, with their served queues, declared concurrency, SDK version, and connect time.

broker info

conveyor broker info

Reports the broker driver (memory or postgres) and its engine statistics (connection-pool counters, row counts, server version).

events

conveyor events [--queue NAME]... [--type TYPE]...

Streams task lifecycle transitions live until interrupted. --queue and --type are repeatable filters; --type is one of enqueued, scheduled, leased, completed, retried, archived, canceled, released. See lifecycle events for the delivery semantics.

conveyor events --queue billing --type completed --type archived

Operating tasks

Command	Effect
conveyor tasks run <id>...	Make one or more scheduled or retry tasks due immediately
conveyor tasks cancel <id>...	Cancel one or more tasks (best-effort for an executing one)
conveyor tasks delete <id>...	Delete one or more non-active tasks
conveyor tasks archive <id>...	Move one or more tasks to the archive (dead-letter)
conveyor tasks reschedule <id> --in DUR (or --at RFC3339)	Move a scheduled, pending, or retry task's due time

run, cancel, delete, and archive take one or more ids: a single id runs the unary call, several run the batch call and report the per-id outcome (use --output json to script it, where even a single id renders the batch shape so your parser does not depend on how many ids you passed). A batch that the server rejected for some or all of its ids prints those outcomes and then exits non-zero, so a scheduled job cannot read a clean exit as work done.

conveyor tasks reschedule 01J... --in 30m
conveyor tasks run 01J...
conveyor tasks delete 01JA... 01JB... 01JC...

Queues, limits, and aggregation

queues

conveyor queues pause <name>
conveyor queues resume <name>

A paused queue keeps its work durable and stops dispatching it.

ratelimit

conveyor ratelimit set <queue> --rate N [--burst N]
conveyor ratelimit rm <queue>
conveyor ratelimit ls

Caps a queue's dispatch rate (token bucket). See rate limiting.

conveyor ratelimit set email --rate 50 --burst 10

concurrency

conveyor concurrency set <queue> --max N
conveyor concurrency rm <queue>
conveyor concurrency ls

Caps how many tasks sharing a concurrency key run at once. See concurrency limits.

conveyor concurrency set email --max 5

group

conveyor group set <queue> [--group KEY] --max-size N --max-delay DUR --grace DUR
conveyor group rm <queue> [--group KEY]
conveyor group ls

Overrides a group's aggregation thresholds. An empty --group sets the queue-wide default applied to every group on the queue without its own override. See group aggregation.

conveyor group set email --group welcome --max-size 20 --max-delay 2m --grace 5s

Cron

conveyor cron add <id> "<spec>" <type> [--queue NAME] [--json PAYLOAD] [--priority N] [--max-retry N]
conveyor cron list
conveyor cron pause <id>
conveyor cron resume <id>
conveyor cron delete <id>

<spec> is a 6-field cron expression. Cron entries are server-persisted, so they survive restarts and failover.

conveyor cron add nightly-report "0 0 2 * * *" report:daily --queue reports

Webhook workers

conveyor webhooks add <name> <url> --queue name[=weight]... --secret SECRET... [--concurrency N] [--batch-type TYPE...] [--request-timeout DUR] [--paused]
conveyor webhooks list
conveyor webhooks pause <name>
conveyor webhooks resume <name>
conveyor webhooks delete <name>

Registers an HTTP endpoint that receives tasks as signed JSON-RPC calls, with no SDK. --queue and --secret are repeatable (two secrets during a rotation). See webhook workers.

conveyor webhooks add billing https://hooks.internal/tasks --queue billing=2 --queue default --secret "$WEBHOOK_SECRET"

Shell completion

conveyor completion bash|zsh|fish|powershell

Generates a completion script for the named shell; follow that command's own output for where to install it.

See also

• Operations guide: deployment, configuration, security, and observability.
• Concepts: the vocabulary the commands operate on.
• End-to-end encryption, rate limiting, concurrency limits, group aggregation, lifecycle events.