> ## Documentation Index > Fetch the complete documentation index at: https://getconvoy.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # CLI 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: ```bash terminal theme={null} brew tap frain-dev/tools brew install convoy ``` The installation procedures for Linux is split into two: * Ubuntu and Debian users * CentOS and RHEL users **Ubuntu and Debian** Install the Convoy CLI from apt repository: ```json terminal theme={null} $ curl -1sLf 'https://dl.cloudsmith.io/public/convoy/convoy/setup.deb.sh' | sudo -E bash $ sudo apt install convoy ``` **CentOS and RHEL OS** Install the Convoy CLI using yum: ```json terminal theme={null} $ curl -1sLf 'https://dl.cloudsmith.io/public/convoy/convoy/setup.rpm.sh' | sudo -E bash $ sudo yum install convoy ``` To install Convoy on Windows, download the binary applicable to your machine: * [Download for AMD64](https://dl.cloudsmith.io/public/convoy/convoy/raw/versions/0.6.6/convoy_0.6.6_windows_amd64.tar.gz) * [Download for ARM64](https://dl.cloudsmith.io/public/convoy/convoy/raw/versions/0.6.6/convoy_0.6.6_windows_arm64.tar.gz) To build Convoy from source code, you need: * Go [version 1.16 or greater](https://golang.org/doc/install). * NodeJS [version 14.17 or greater](https://nodejs.org/). * Npm [version 6 or greater](https://npmjs.com/). ```json theme={null} $ git clone https://github.com/frain-dev/convoy.git && cd convoy $ make build ``` Verify the build by running the command below: ```json terminal theme={null} $ 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: ```txt terminal theme={null} $ 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 | Command | Purpose | | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`convoy server`** | Control plane: dashboard and management HTTP API on **`server.http.port`** (flag **`--port`**). | | **`convoy agent`** | Data plane: queue consumers, broker ingest, SMTP-backed notifications, and data-plane HTTP (including **`/metrics`**) on **`server.http.agent_port`** (flag **`--port`**). | | **`convoy migrate up`** | Apply 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 config`** | Print the resolved configuration as JSON (same merge rules as other commands: **`cli flags`** > **`environment variables`** > **`convoy.json`**—see [Configuration](/docs/deployment/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](/docs/deployment/architecture) and [Configuration](/docs/deployment/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](https://github.com/frain-dev/convoy/blob/main/docker-compose.dev.yml). See the [core gateway changelog](/docs/changelog/core-gateway) for the unified agent change. ### Bootstrap Command: `convoy bootstrap` #### Synopsis ```txt terminal theme={null} $ 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` with subcommands **`up`**, **`down`**, and **`create`**. #### Synopsis ```txt terminal theme={null} $ 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 ```txt terminal theme={null} $ 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](https://github.com/frain-dev/convoy/blob/main/cmd/config/config.go)). Use it to verify effective values; precedence is **`cli flags`** > **`environment variables`** > **`convoy.json`** (see [Configuration](/docs/deployment/configuration)). It does not start HTTP services or run migrations. #### Command Flags * **`--help`**: Help for the `config` command. ### Server Command: `convoy server` #### Synopsis ```txt terminal theme={null} $ 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](#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](/docs/deployment/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](/docs/product-manual/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 ```txt terminal theme={null} $ 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](https://github.com/frain-dev/convoy/blob/main/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 ```txt terminal theme={null} $ 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.