Skip to main content
Convoy ships with a very easy-to-use command-line interface (CLI). Refer to the navigation to the right for a list of subcommands.

Install the CLI

The Convoy CLI can be installed directly from your package manager or by building from the GitHub source:
Install the Convoy CLI to your Mac from brew:
terminal

Using the CLI

To view the list of the available commands at any time, just run convoy in your terminal with no arguments:
terminal
Global flags (database, Redis, tracing, metrics, billing, feature flags, rate limits, and so on) are defined on the root command; run convoy --help on your installed binary for the authoritative list for that version. To get help for a subcommand, pass -h (for example convoy agent -h).

Core commands

Typical production layout: one or more server replicas behind a load balancer and multiple agent replicas; both use the same convoy.json (or equivalent env). See Architecture and Configuration.

Historical CLI commands

Older docs referred to convoy worker, convoy ingest, convoy stream, and convoy scheduler. Current Convoy exposes convoy server for the control-plane HTTP API and convoy agent for the data plane (queue consumers, broker ingest, and data-plane HTTP including /metrics on server.http.agent_port). A common local layout is convoy server on the API port and convoy agent on the agent port—for example 5005 / 5008 in docker-compose.dev.yml. See the core gateway changelog for the unified agent change.

Bootstrap

Command: convoy bootstrap

Synopsis

terminal

Description

convoy bootstrap creates a user and a default organisation (the usual first-time self-hosted setup). On success it prints user_id and organisation_id plus email/password. If that email already exists, it exits cleanly without recreating the user and without reprinting credentials or IDs. With --with-api-key, bootstrap also mints a personal API key and prints it. Use that key with POST /api/v1/projects?orgID=... to create projects without logging in through the dashboard. --api-key-name labels the key. --api-key-expiration sets lifetime in days; unset or 0 defaults to 24 hours. Rerunning bootstrap for an existing user does not mint another key.

Command Flags

  • --email: User email (required).
  • --first-name / --last-name: Optional name fields (defaults admin).
  • --format: Output format (json by default).
  • --with-api-key: Mint and print a personal API key.
  • --api-key-name: Label for the minted key (requires --with-api-key).
  • --api-key-expiration: Lifetime in days; 0 means the 24h default (requires --with-api-key).
  • --help: Help for the bootstrap command.

Migrate

Command: convoy migrate with subcommands up, down, and create.

Synopsis

terminal
Run convoy migrate up (alias migrate-up) to apply pending schema changes. It uses the same database settings as the rest of the CLI (--config, CONVOY_DB_*, or --db-* flags). For the full global flag list, run convoy migrate up --help on your binary.

Description

Use migrate up in deploy scripts and release runbooks before starting server and agent. migrate down rolls back (optional --max on down—see convoy migrate down --help). migrate create is for Convoy developers adding SQL migrations.

Command Flags

  • up: Apply all pending migrations.
  • down: Roll back migrations (see subcommand help for options).
  • create: Generate a new migration file (development workflow).

Config

Command: convoy config

Synopsis

terminal
Global flags are the same as the root command; run convoy config --help for the full list.
Description
convoy config loads configuration the same way server and agent do, then prints the merged struct as indented JSON (implementation). Use it to verify effective values; precedence is cli flags > environment variables > convoy.json (see Configuration). It does not start HTTP services or run migrations.

Command Flags

  • --help: Help for the config command.

Server

Command: convoy server

Synopsis

terminal
Global flags are the same as the root command; run convoy server --help on your binary for the full list.

Description

The server command runs Convoy’s control-plane HTTP API (dashboard, configuration, and management endpoints). For split deployments, run convoy agent separately for the data plane (ingest, queue consumers, and data-plane HTTP on server.http.agent_port). See Historical CLI commands above.

Command Flags

  • --port: HTTP port for the control server (overrides server.http.port in config when set).
  • --api-auth / --basic-auth: Optional inline API key or basic-auth credentials for the server process.
  • --cache, --limiter: Redis vs in-memory cache and rate limiter backends.
  • --env, --logger, --host, --root-path: Process environment, logging, hostname, and path prefix behind a reverse proxy.
  • --max-response-size: Cap on stored subscriber response payload size (see configuration).
  • --native: Enable native-realm authentication.
  • --promaddr: Listed on convoy server --help as “Prometheus dsn”; prefer metrics in convoy.json, CONVOY_METRICS_*, and root --metrics-* flags for Prometheus export (see Metrics).
  • --proxy: Outbound HTTP proxy for the server process.
  • --ssl, --ssl-cert-file, --ssl-key-file: TLS for the control HTTP server.

Agent

Command: convoy agent

Synopsis

terminal
Global flags are the same as the root command; run convoy agent --help on your binary for the full list.

Description

The agent command runs the data plane: queue consumers, broker-backed ingest (where configured), notification paths that need SMTP, and the data-plane HTTP server on server.http.agent_port (CLI --port overrides that value when non-zero). Run one or more agent replicas alongside convoy server; docker-compose.dev.yml maps this to service agent (for example port 5008).

Command Flags

  • --port: Agent HTTP port (maps to server.http.agent_port / AGENT_PORT in config).
  • --consumers: Consumer pool size when set to a non-negative value (otherwise config defaults apply).
  • --interval: Seconds between in-memory config syncs from the database.
  • --mode: Worker execution mode: events, retry, or default (see configuration / license notes for your build).
  • --smtp-*: SMTP settings for notification email from the agent process.

Retry

Command: convoy retry

Synopsis

terminal

Description

convoy retry selects event deliveries matching --status and --time and re-queues them for delivery. Use it for operational recovery after incidents or misconfiguration; it does not replace normal retry policies on each endpoint.

Command Flags

  • --status: This is used to specify the status of event delivery to re-queue.
  • --time: This is used to specify how far in the past to look for event deliveries. It accepts a duration string. Duration strings are like integers followed by a time unit. E.g. 1h, 300ms, or 2h45m etc.