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:
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:
$ convoy
High Performance Webhooks Gateway
Usage:
Convoy [command]
Available Commands:
bootstrap bootstrap creates a new user account
completion generate the autocompletion script for the specified shell
config config outputs your instances computed configuration
help Help about any command
ingest Ingest webhook events from Pub/Sub streams
migrate Convoy migrations
retry retry event deliveries with a particular status in a timeframe
scheduler scheduler runs periodic tasks
server Start the HTTP server
stream Start a websocket server to pipe events to a convoy cli instance
version Print the version
worker Start worker instance
Flags:
--config string Configuration file for convoy (default "./convoy.json")
--license-key string License key
--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
-h, --help help for Convoy
--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
-v, --version version for Convoy
To get help for any specific command, pass the -h flag to the relevant subcommand. For example, to get help about the worker sub-command run convoy worker -h
Ingest
Command: convoy ingest
Synopsis
$ convoy ingest --help
Ingest webhook events from Pub/Sub streams
Usage:
Convoy ingest [flags]
Flags:
-h, --help help for ingest
--interval int the time interval, measured in seconds, at which the database should be polled for new pub sub sources (default 300)
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
Command Flags
--interval: The time in seconds to poll the database for changes in the source configuration.
Bootstrap
Command: convoy bootstrap
Synopsis
$ 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.
Stream
Command: convoy stream
Synopsis
$ convoy stream --help
Start a websocket server to pipe events to a convoy cli instance
Usage:
Convoy stream [flags]
Flags:
-h, --help help for stream
--log-level string stream log level (default "error")
--socket-port uint32 Socket port (default 5008)
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 stream command starts a websocket server to pipe events to another convoy instance.
Command Flags
--help: Get help on the stream command.
Migrate
Command: convoy migrate
Synopsis
$ 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
$ 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 worker.
Server
Command: convoy server
Synopsis
$ 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")
--disable-endpoint Disable all application endpoints
--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")
--log-level string Log level (default "error")
--logger string Logger (default "info")
--max-response-size uint Max response size
--multi-tenant Start convoy in single- or multi-tenant mode
--native Enable native-realm authentication
--new-relic-app string NewRelic application name
--new-relic-config-enabled Enable new-relic config
--new-relic-key string NewRelic application license key
**--new-relic-**tracer-enabled Enable new-relic distributed tracer
--port uint32 Server port
--promaddr string Prometheus dsn
--proxy string HTTP Proxy
--replay-attacks Enable feature to prevent replay attacks
--retry-interval uint Endpoint retry interval
--retry-limit uint Endpoint retry limit
--retry-strategy string Endpoint retry strategy
--searcher string Searcher
--sentry string Sentry DSN
--signature-hash string Application signature hash
--signature-header string Application signature header
--ssl Configure SSL
--ssl-cert-file string SSL certificate file
--ssl-key-file string SSL key file
--typesense-api-key string Typesense Api Key
--typesense-host string Typesense Host
--worker-port uint32 Worker port
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 server command runs convoy’s REST API. The REST API is the primary entry point to using convoy and this command is likely the most important command.
Command Flags
-
--port: This flag specifies the port number the server listens on. This is a required parameter that must be configured from one of the configuration sources.
-
--auth: This flag specifies if the REST API will require authentication or not. It is enabled by default
-
--multi-tenant: This flag specifies the mode the instance is running. It’s a boolean flag. When set to true . The server will only receive events but not run workers in the background. It is expected that you will run convoy worker as a different process to consume event deliveries off the queue. Defaults to false.
-
--max-response-size: This flag specifies the maximum response in bytes of the endpoint’s payload to store. This configuration only affects the default group.
-
--native: This flag specifies if the native realm should be enabled. You can read more about the native realm here It is a boolean flag. Defaults to false.
-
--disable-endpoint: This flag specifies the disable-endpoint configuration for the default group for convoy instances running in non-multi tenant mode.Defaults to false.
-
--signature-hash: This flag specifies the hash algorithm for the default group for convoy instances running in non-multi tenant mode.
-
--signature-header: This flag specifies the HTTP header for the default group for convoy instances running in non-multi tenant mode.
-
--sentry: This flag specifies the DSN to push telemetry data to sentry.
-
--ssl: This specifies if the server should run with ssl enabled. If true, then you must specify two other flags --ssl-cert-file and --ssl-key-file.
-
--ssl-cert-file: This is a path to the SSL certificate file. If specified and ssl is set to false; nothing happens.
-
--ssl-key-file: This is a path to the SSL key file. If specified and ssl is set to false; nothing happens.
-
--with-workers: This specifies if the server should run in monolith mode. This means both the server and worker will be run in the same process. Defaults to true if not specified.
Worker
Command: convoy worker
Synopsis
$ convoy worker -h
Start worker instance
Usage:
Convoy worker [flags]
Flags:
-h, --help help for worker
--log-level string scheduler log level
--new-relic-app string NewRelic application name
--new-relic-config-enabled Enable new-relic config
--new-relic-key string NewRelic application license key
--new-relic-tracer-enabled Enable new-relic distributed tracer
--smtp-from string Sender email address
--smtp-password string SMTP authentication password
--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
--worker-port uint32 Worker port (default 5006)
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 worker command is used when running convoy in the micro-services mode. It does the job by simply reading event deliveries of the queue and passing them to consumers to process. It is possible to run multiple worker processes to scale up your workers.
This command requires all Global configurations to be set either through the CLI or the configuration file. This is because the workers need to connect to both the database and the queues to perform its duty.
Command Flags
--smtp-provider: This flag specifies the name of the SMTP provider. While this isn’t necessary for smtp configuration, it is used to provider rich log.--smtp-from: This specifies the sender’s email address when sending notification emails.--smtp-url: This specifies the smtp servers’ url. You should lookup the providers’ documentation on how to specify this flag.--smtp-port: This specifies the smtp servers’ port. You should lookup the providers’ documentation o how to specify this flag.--smtp-reply-to: This specifies the email to use as reply-to in notification emails sent.--smtp-username: This specifies the username for smtp authentication. You should lookup the providers’ documentation on how to specify this flag.--smtp-password: This specifies the password for smtp authentication. You should lookup the providers’ documentation on how to specify this flag.--smtp-ssl: This specifies if ssl should be used in the smtp protocol for sending emails.--help: Get help on the worker command.--worker-port: Specify the worker server’s port. Defaults to 5006 if not specified.--mode: The processing mode of the events’ processor.
Agent
Command: convoy agent
$ convoy agent -h
Start agent instance
Usage:
Convoy agent [flags]
Flags:
--agent-port uint32 Agent port
--consumers int Size of the consumers pool. (default -1)
-h, --help help for agent
--ingest-port uint32 Ingest port
--interval int the time interval, measured in seconds to update the in-memory store from the database (default 10)
--log-level string scheduler log level
--mode string Execution Mode (one of events, retry and default)
--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
--worker-port uint32 Worker port
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
--enable-feature-flag strings List of feature flags to enable e.g. "full-text-search,prometheus"
--enable-profiling Enable profiling and exporting profile data to pyroscope
--max-retry-seconds uint Max retry seconds exponential backoff (default 7200)
--metrics-backend string Metrics backend e.g. prometheus. ('prometheus' feature flag required (default "prometheus")
--metrics-prometheus-sample-time uint Prometheus metrics sample time (default 5)
--otel-auth-header-name string OTel backend auth header name
--otel-auth-header-value string OTel backend auth header value
--otel-collector-url string OTel collector URL
--otel-sample-rate float OTel tracing sample rate (default 1)
--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
--retention-policy string SMTP Port
--retention-policy-enabled SMTP Port
--sentry-dsn string Sentry backend dsn
--tracer-type string Tracer backend, e.g. sentry, datadog or otel
Description
The worker command is used when running convoy in the microservices’ mode.
It does the job by simply reading event deliveries of the queue and passing them to consumers to process.
It is possible to run multiple worker processes to scale up your workers.
This command requires all Global configurations to be set either through the CLI or the configuration file.
This is because the workers need to connect to both the database and the queues to perform its duty.
Command Flags
--smtp-provider: This flag specifies the name of the SMTP provider. While this isn’t necessary for smtp configuration, it is used to provider rich log.--smtp-from: This specifies the sender’s email address when sending notification emails.--smtp-url: This specifies the smtp servers’ url. You should look up the providers’ documentation on how to specify this flag.--smtp-port: This specifies the smtp servers’ port. You should look up the providers’ documentation on how to specify this flag.--smtp-reply-to: This specifies the email to use as reply-to in notification emails sent.--smtp-username: This specifies the username for smtp authentication. You should look up the providers’ documentation on how to specify this flag.--smtp-password: This specifies the password for smtp authentication. You should look up the providers’ documentation on how to specify this flag.--smtp-ssl: This specifies if ssl should be used in the smtp protocol for sending emails.--help: Get help on the worker command.--agent-port: Specify the agent server’s port. Defaults to 5007 if not specified.--interval: The time in seconds to poll the database for changes in the source configuration.--mode: The processing mode of the events’ processor.
Retry
Command: convoy retry
Synopsis
$ 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.
