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, and so on) are defined on the root command; run convoy --help on your installed binary for the full list for that version. To get help for a subcommand, pass -h (for example convoy agent -h).

​
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

​
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

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

The migrate command is responsible for running pending migrations and rolling back migrations.

​
Command Flags

  • down: Rollback migrations.
  • up: Run all pending migrations

​
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:
      --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
The config command outputs the configuration for your active instances.

​
Command Flags

  • --help: Get help on 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: Appears on convoy server --help as “Prometheus dsn”; it is not passed through in buildServerCliConfiguration in current source—use root metrics flags / convoy.json for Prometheus settings instead.
  • --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

At core, convoy is an asynchronous messaging service. It relies on message brokers to carry out its duty. This command is used to filter event deliveries that match the filters set; it will purge the queues for all matched event deliveries and re-enqueue them all.

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