CLI - Convoy

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:

Mac
Linux
Windows
Source

Install the Convoy CLI to your Mac from brew:

terminal

brew tap frain-dev/tools
brew install convoy

The installation procedures for Linux is split into two:

Ubuntu and Debain users
CentOS and RHEL users

Ubuntu and Debain OSInstall the Convoy CLI from apt repository:

terminal

$ curl -1sLf 'https://dl.cloudsmith.io/public/convoy/convoy/setup.deb.sh' | sudo -E bash
$ sudo apt install convoy

CentOS and RHEL OSInstall the Convoy CLI using yum:

terminal

$ curl -1sLf 'https://dl.cloudsmith.io/public/convoy/convoy/setup.rpm.sh' | sudo -E bash
$ sudo yum install convoy

To build Convoy from source code, you need:

$ git clone https://github.com/frain-dev/convoy.git && cd convoy
$ make build

Verify the build by running the command below:

terminal

$ convoy -v
Convoy version v0.6.0

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:
      --api-key-expiration int   API key lifetime in days; 0 uses the default (24h). Rerun on an existing user will not re-mint (requires --with-api-key)
      --api-key-name string      Name for the minted API key (requires --with-api-key) (default "bootstrap-key")
      --email string             Email
      --first-name string        First name (default "admin")
      --format string            Output Format (default "json")
  -h, --help                     help for bootstrap
      --last-name string         Last name (default "admin")
      --with-api-key             Also mint and print a personal API key for the user

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

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.

​Install the CLI

​Using the CLI

​Historical CLI commands

​Bootstrap

​Synopsis

​Description

​Command Flags

​Migrate

​Synopsis

​Description

​Command Flags

​Config

​Synopsis

Description

​Command Flags

​Server

​Synopsis

​Description

​Command Flags

​Agent

​Synopsis

​Description

​Command Flags

​Retry

​Synopsis

​Description

​Command Flags

Install the CLI

Using the CLI

Historical CLI commands

Bootstrap

Synopsis

Description

Command Flags

Migrate

Synopsis

Description

Command Flags

Config

Synopsis

Command Flags

Server

Synopsis

Description

Command Flags

Agent

Synopsis

Description

Command Flags

Retry

Synopsis

Description

Command Flags