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
brew tap frain-dev/tools
brew install convoy

​
Using the CLI

To view the list of the available commands at any time, just run convoy in your terminal with no arguments:
terminal
$ convoy
High Performance Webhooks Gateway

Usage:
  Convoy [command]

Available Commands:
  agent         Start agent instance
  bootstrap     bootstrap creates a new user account
  completion    Generate the autocompletion script for the specified shell
  config        config outputs your instances computed configuration
  feature-flags Print the list of feature flags
  help          Help about any command
  migrate       Convoy migrations
  openapi       Extract webhook schemas from OpenAPI specifications
  retry         retry event deliveries with a particular status in a timeframe
  server        Start the HTTP server
  utils         runs utility commands
  version       Print the version

Use "Convoy [command] --help" for more information about a command.
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

CommandPurpose
convoy serverControl plane: dashboard and management HTTP API on server.http.port (flag --port).
convoy agentData plane: queue consumers, broker ingest, SMTP-backed notifications, and data-plane HTTP (including /metrics) on server.http.agent_port (flag --port).
convoy migrate upApply all pending database migrations against the DB from your config / flags. Run before starting server and agent in a new environment or after upgrading.
convoy configPrint the resolved configuration as JSON (same merge rules as other commands: cli flags > environment variables > convoy.json—see Configuration). Use the same --config and environment as the process you are inspecting.
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
$ convoy bootstrap --help
bootstrap creates a new user account

Usage:
  Convoy bootstrap [flags]

Flags:
      --email string        Email
      --first-name string   Email (default "admin")
      --format string       Output Format (default "json")
  -h, --help                help for bootstrap
      --last-name string    Email (default "admin")

Global Flags:
      --config string           Configuration file for convoy (default "./convoy.json")
      --db-database string      Database Database
      --db-host string          Database Host
      --db-options string       Database Options
      --db-password string      Database Password
      --db-port int             Database Port
      --db-scheme string        Database Scheme
      --db-type string          Database provider
      --db-username string      Database Username
      --redis-database string   Redis database
      --redis-host string       Redis Host
      --redis-password string   Redis Password
      --redis-port int          Redis Port
      --redis-scheme string     Redis Scheme
      --redis-type string       Redis provider
      --redis-username string   Redis Username

​
Description

The bootstrap creates a new user account.

​
Command Flags

  • --help: Get help on the bootstrap command.

​
Migrate

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

​
Synopsis

terminal
$ convoy migrate --help
Convoy migrations

Usage:
  Convoy migrate [command]

Available Commands:
  create      creates a new migration file
  down        Rollback migrations
  up          Run all pending migrations

Flags:
  -h, --help   help for migrate
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
$ convoy config -h
config outputs your instances computed configuration

Usage:
  Convoy config [flags]

Flags:
  -h, --help   help for config
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
$ convoy server --help
Start the HTTP server

Usage:
  Convoy server [flags]

Aliases:
  server, serve, s

Flags:
      --api-auth string          API-Key authentication credentials
      --basic-auth string        Basic authentication credentials
      --cache string             Cache Provider ("redis" or "in-memory") (default "redis")
      --env string               Convoy environment (default "development")
  -h, --help                     help for server
      --host string              Host - The application host name
      --limiter string           Rate limiter provider ("redis" or "in-memory") (default "redis")
      --logger string            Logger (default "info")
      --max-response-size uint   Max response size
      --native                   Enable native-realm authentication
      --port uint32              Server port
      --promaddr string          Prometheus dsn
      --proxy string             HTTP Proxy
      --root-path string         Root path for routing behind load balancers (e.g., /convoy)
      --ssl                      Configure SSL
      --ssl-cert-file string     SSL certificate file
      --ssl-key-file string      SSL key file
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
$ convoy agent -h
Start agent instance

Usage:
  Convoy agent [flags]

Flags:
      --consumers int          Size of the consumers pool. (default -1)
  -h, --help                   help for agent
      --interval int           the time interval, measured in seconds to update the in-memory store from the database (default 10)
      --mode string            Execution Mode (one of events, retry and default)
      --port uint32            Agent port
      --smtp-from string       Sender email address
      --smtp-password string   SMTP authentication password
      --smtp-port uint32       SMTP Port
      --smtp-provider string   SMTP provider
      --smtp-reply-to string   Email address to reply to
      --smtp-ssl               Enable SMTP SSL
      --smtp-url string        SMTP provider URL
      --smtp-username string   SMTP authentication username
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
$ convoy retry -h
retry event deliveries with a particular status in a timeframe

Usage:
  Convoy retry [flags]

Flags:
  -h, --help            help for retry
      --status string   Status of event deliveries to re-queue
      --time string     Time interval

Global Flags:
      --config string           Configuration file for convoy (default "./convoy.json")
      --db-database string      Database Database
      --db-host string          Database Host
      --db-options string       Database Options
      --db-password string      Database Password
      --db-port int             Database Port
      --db-scheme string        Database Scheme
      --db-type string          Database provider
      --db-username string      Database Username
      --redis-database string   Redis database
      --redis-host string       Redis Host
      --redis-password string   Redis Password
      --redis-port int          Redis Port
      --redis-scheme string     Redis Scheme
      --redis-username string   Redis Username

​
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.