FerryDocs
Reference

CLI reference

Every ferry command, argument and option, generated from the CLI itself.

This page lists every ferry command with its arguments and options. It is generated from the CLI's own help (ferry markdown-help), so it matches the binary built from this repository. In a terminal, ferry <command> --help prints the same text.

Connecting to a server

Every command talks to a Ferry server. ferry login --server URL opens the dashboard, where you approve the terminal; it then gets an API token of its own, saved with the server in ~/.config/ferry/config.json ($XDG_CONFIG_HOME/ferry/config.json when that variable is set). With --token TOKEN, that token is verified and saved instead. The --server / --token flags, then the FERRY_SERVER / FERRY_TOKEN variables, take precedence over the saved values. See Set up the CLI.

Command overview

ferry

Command-line client for Ferry, a self-hosted Render alternative

Usage

ferry [OPTIONS] <COMMAND>

Connection: --server/--token flags, else FERRY_SERVER/FERRY_TOKEN, else the server and token saved by 'ferry login'.

Subcommands

  • login — Connect this terminal to a server and save the connection
  • info — Show server information
  • services — List services
  • create — Create a service
  • show — Show a service's settings and state
  • update — Change a service's settings
  • delete — Delete a service with its containers and deploy history
  • deploy — Trigger a deploy
  • up — Upload a local directory and deploy it (creates the service if needed)
  • deploys — List a service's deploys, newest first
  • cancel — Cancel a queued or in-progress deploy
  • rollback — Roll back to a previous deploy's image
  • restart — Redeploy the live image with the current settings and environment
  • suspend — Stop a service's containers (the proxy answers 503)
  • resume — Resume a suspended service
  • scale — Set the number of instances
  • status — Show running instances with CPU and memory usage
  • logs — Show runtime, deploy or job logs
  • env — List or change a service's environment variables
  • domains — The server's domains (services are served at <service>.<domain>), or a service's custom domains
  • certificates — Show the certificate of every hostname the server routes
  • run — Run a one-off job (or trigger a cron job now)
  • jobs — List a service's job runs, or cancel one
  • db — Manage Postgres and Redis datastores
  • env-group — Manage environment groups
  • blueprint — Apply a ferry.yaml / render.yaml blueprint
  • open — Print (and try to open) a service's URL
  • deploy-hook — Show or rotate a service's deploy hook (a secret URL that triggers a deploy)

Options

OptionDescription
--server <URL>Ferry API URL, e.g. http://127.0.0.1:7878 [env: FERRY_SERVER]
--token <TOKEN>API token [env: FERRY_TOKEN]
--jsonPrint the raw API JSON instead of formatted output

ferry login

Connect this terminal to a server and save the connection

Without a token, opens the dashboard to approve the login there: sign in, check that the page shows the code the terminal prints, approve. The server then gives this terminal an API token of its own, which you can revoke in the dashboard. With --token (or FERRY_TOKEN), that token is verified and saved instead: for servers without a browser at hand, scripts and CI.

Usage

ferry login [OPTIONS]

Options

OptionDescription
--no-browserOnly print the page to open, without opening a browser

ferry info

Show server information

Usage

ferry info

ferry services

List services

Usage

ferry services

Command Alias: ls

ferry create

Create a service

Usage

ferry create [OPTIONS] <NAME>

Arguments

ArgumentDescription
<NAME>Service name (lowercase letters, digits and '-')

Options

OptionDescription
-t, --type <TYPE>Service type: web, pserv, worker, cron, static
--repo <URL>Git repository URL, or the path of a git repository on the server (a relative path that exists here is sent as an absolute path)
--branch <BRANCH>Git branch (default: main)
--image <IMAGE>Prebuilt Docker image
--runtime <RUNTIME>Runtime: auto, docker, image, node, python, go, rust, ruby, static
--root-dir <DIR>Build context subdirectory (monorepos)
--dockerfile <PATH>Dockerfile path relative to the root dir
--build-cmd <CMD>Build command (native runtimes)
--start-cmd <CMD>Start command (run with sh -c)
--publish-dir <DIR>Directory of built files to serve (static sites)
--port <PORT>Container port the app listens on (--port 0 clears the port setting: Ferry detects it)
--health <PATH>Health check path, e.g. /healthz
--instances <N>Number of instances
--schedule <CRON>Cron schedule (cron jobs), e.g. "*/5 * * * *"
--disk <MOUNT>Mount a persistent disk at this path (limits the service to 1 instance)
--domain <DOMAIN>Custom domain (repeatable)
--memory <SIZE>Memory limit of each instance and job run, e.g. 512M or 1G (a plain number is MiB; 'default' = the server's default)
--cpu <CPUS>CPU limit of each instance and job run, e.g. 0.5, 2 or 500m ('default' = the server's default)
-e, --env <KEY=VALUE>Environment variable (repeatable)
--env-group <GROUP>Link an environment group (repeatable)
--no-auto-deployDon't redeploy on git push
--no-deployDon't queue the first deploy
-f, --followStream the first deploy's logs until it finishes (exit 1 if it fails)

ferry show

Show a service's settings and state

Usage

ferry show <NAME>

Arguments

ArgumentDescription
<NAME>Service name or id

ferry update

Change a service's settings

Usage

ferry update [OPTIONS] <NAME>

Clearing settings: pass an empty value to a text setting (--start-cmd "", --health "", ...), --port 0 to clear the port setting (Ferry then detects the port again), and --memory default / --cpu default to go back to the server's default limits. Build & deploy settings apply to the next deploy; resource limits to the next deploy or restart ('ferry restart NAME'); the start command of a cron job applies from its next run.

Arguments

ArgumentDescription
<NAME>Service name or id

Options

OptionDescription
--repo <URL>Git repository URL or server-side path ("" clears; a relative path that exists here is sent as an absolute path)
--branch <BRANCH>Git branch
--image <IMAGE>Prebuilt Docker image ("" clears)
--runtime <RUNTIME>Runtime: auto, docker, image, node, python, go, rust, ruby, static
--root-dir <DIR>Build context subdirectory (monorepos)
--dockerfile <PATH>Dockerfile path relative to the root dir
--build-cmd <CMD>Build command (native runtimes)
--start-cmd <CMD>Start command (run with sh -c)
--publish-dir <DIR>Directory of built files to serve (static sites)
--port <PORT>Container port the app listens on (--port 0 clears the port setting: Ferry detects it)
--health <PATH>Health check path, e.g. /healthz
--instances <N>Number of instances
--schedule <CRON>Cron schedule (cron jobs), e.g. "*/5 * * * *"
--disk <MOUNT>Mount a persistent disk at this path (limits the service to 1 instance)
--domain <DOMAIN>Custom domain (repeatable)
--memory <SIZE>Memory limit of each instance and job run, e.g. 512M or 1G (a plain number is MiB; 'default' = the server's default)
--cpu <CPUS>CPU limit of each instance and job run, e.g. 0.5, 2 or 500m ('default' = the server's default)
--auto-deployRedeploy on git push
--no-auto-deployDon't redeploy on git push

ferry delete

Delete a service with its containers and deploy history

Usage

ferry delete [OPTIONS] <NAME>

Command Alias: rm

Arguments

ArgumentDescription
<NAME>Service name or id

Options

OptionDescription
-y, --yesDon't ask for confirmation
--forceDelete even if other services still reference it (their next deploy or restart will fail)

ferry deploy

Trigger a deploy

Usage

ferry deploy [OPTIONS] <NAME>

Arguments

ArgumentDescription
<NAME>Service name or id

Options

OptionDescription
--commit <SHA>Build this exact commit (git services)
--clear-cacheBuild without the Docker layer cache
-f, --followStream the build/deploy logs until it finishes (exit 1 if it fails)

ferry up

Upload a local directory and deploy it (creates the service if needed)

Usage

ferry up [OPTIONS] [NAME]

If the service doesn't exist, it is created with these flags. If it exists, the build & deploy settings (--runtime, --start-cmd, --port, ...) are applied to it first, like 'ferry update'; -e sets variables like 'ferry env set --no-restart'; --env-group links groups. Only --type is used solely when creating the service (an existing service keeps its type).

Arguments

ArgumentDescription
<NAME>Service name or id (default: derived from the directory name)

Options

OptionDescriptionDefault
-d, --dir <DIR>Directory to upload.
-t, --type <TYPE>Service type, only used when creating the service: web, pserv, worker, cron, static [default: web]
--runtime <RUNTIME>Runtime: auto, docker, image, node, python, go, rust, ruby, static
--root-dir <DIR>Build context subdirectory (monorepos)
--dockerfile <PATH>Dockerfile path relative to the root dir
--build-cmd <CMD>Build command (native runtimes)
--start-cmd <CMD>Start command (run with sh -c)
--publish-dir <DIR>Directory of built files to serve (static sites)
--port <PORT>Container port the app listens on (--port 0 clears the port setting: Ferry detects it)
--health <PATH>Health check path, e.g. /healthz
--instances <N>Number of instances
--schedule <CRON>Cron schedule (cron jobs), e.g. "*/5 * * * *"
--disk <MOUNT>Mount a persistent disk at this path (limits the service to 1 instance)
--domain <DOMAIN>Custom domain (repeatable)
--memory <SIZE>Memory limit of each instance and job run, e.g. 512M or 1G (a plain number is MiB; 'default' = the server's default)
--cpu <CPUS>CPU limit of each instance and job run, e.g. 0.5, 2 or 500m ('default' = the server's default)
-e, --env <KEY=VALUE>Environment variable, set before deploying (repeatable)
--env-group <GROUP>Link an environment group before deploying (repeatable)
--clear-cacheBuild without the Docker layer cache
-f, --followStream the build/deploy logs until it finishes (exit 1 if it fails)

ferry deploys

List a service's deploys, newest first

Usage

ferry deploys [OPTIONS] <NAME>

Arguments

ArgumentDescription
<NAME>Service name or id

Options

OptionDescriptionDefault
-n, --limit <N>Maximum number of entries20

ferry cancel

Cancel a queued or in-progress deploy

Usage

ferry cancel <DEPLOY_ID>

Arguments

ArgumentDescription
<DEPLOY_ID>Deploy id

ferry rollback

Roll back to a previous deploy's image

Usage

ferry rollback [OPTIONS] <NAME> <DEPLOY_ID>

Arguments

ArgumentDescription
<NAME>Service name or id
<DEPLOY_ID>Deploy to roll back to

Options

OptionDescription
-f, --followStream the deploy logs until it finishes (exit 1 if it fails)

ferry restart

Redeploy the live image with the current settings and environment

Usage

ferry restart [OPTIONS] <NAME>

Arguments

ArgumentDescription
<NAME>Service name or id

Options

OptionDescription
-f, --followStream the build/deploy logs until it finishes (exit 1 if it fails)

ferry suspend

Stop a service's containers (the proxy answers 503)

Usage

ferry suspend <NAME>

Arguments

ArgumentDescription
<NAME>Service name or id

ferry resume

Resume a suspended service

Usage

ferry resume <NAME>

Arguments

ArgumentDescription
<NAME>Service name or id

ferry scale

Set the number of instances

Usage

ferry scale <NAME> <INSTANCES>

Arguments

ArgumentDescription
<NAME>Service name or id
<INSTANCES>Number of instances

ferry status

Show running instances with CPU and memory usage

Usage

ferry status <NAME>

Arguments

ArgumentDescription
<NAME>Service name or id

ferry logs

Show runtime, deploy or job logs

Usage

ferry logs [OPTIONS] <NAME|--deploy <DEPLOY_ID>|--job <JOB_ID>>

Arguments

ArgumentDescription
<NAME>Service name or id (runtime logs)

Options

OptionDescription
--deploy <DEPLOY_ID>Show a deploy's build/deploy log instead
--job <JOB_ID>Show a job run's log instead
-f, --followKeep streaming new lines
-n, --tail <N>Number of recent lines per instance (runtime logs)

ferry env

List or change a service's environment variables

Usage

ferry env [OPTIONS] <NAME>
ferry env <COMMAND>

Subcommands

  • ls — List variables as KEY=VALUE (values with newlines or quotes are printed double-quoted with backslash escapes)
  • set — Set variables (restarts the service unless --no-restart)
  • unset — Remove variables (restarts the service unless --no-restart)

Arguments

ArgumentDescription
<NAME>Service name or id (lists its variables)

Options

OptionDescription
--effectiveList the merged environment: linked env groups, then the service's own variables

ferry env ls

List variables as KEY=VALUE (values with newlines or quotes are printed double-quoted with backslash escapes)

Usage

ferry env ls [OPTIONS] <NAME>

Command Alias: list

Arguments

ArgumentDescription
<NAME>Service name or id

Options

OptionDescription
--effectiveList the merged environment: linked env groups, then the service's own variables

ferry env set

Set variables (restarts the service unless --no-restart)

Usage

ferry env set [OPTIONS] <NAME> <KEY=VALUE>...

Arguments

ArgumentDescription
<NAME>Service name or id
<KEY=VALUE>KEY=VALUE pairs. Values may reference ${{datastore.NAME.connectionString}}, ${{service.NAME.hostport}}, … (resolved when the service starts)

Options

OptionDescription
--no-restartSave without restarting
-f, --followStream the restart's logs until it finishes (exit 1 if it fails)

ferry env unset

Remove variables (restarts the service unless --no-restart)

Usage

ferry env unset [OPTIONS] <NAME> <KEY>...

Arguments

ArgumentDescription
<NAME>Service name or id
<KEY>Variable names

Options

OptionDescription
--no-restartSave without restarting
-f, --followStream the restart's logs until it finishes (exit 1 if it fails)

ferry domains

The server's domains (services are served at <service>.<domain>), or a service's custom domains

Usage

ferry domains [NAME]
ferry domains <COMMAND>

Subcommands

  • connect — Connect a domain to the server: services are then served at <service>.DOMAIN. Prints the DNS record to create
  • verify — Check now whether a domain's DNS points at this server (exit 1 while it doesn't)
  • default — Make a domain the default one: the domain of the URL services are shown with
  • disconnect — Disconnect a domain from the server: services stop being served under it
  • ls — List a service's custom domains
  • add — Add a custom domain to a service
  • rm — Remove a custom domain from a service

Arguments

ArgumentDescription
<NAME>Service name or id: lists its custom domains. Without it: the server's domains

ferry domains connect

Connect a domain to the server: services are then served at <service>.DOMAIN. Prints the DNS record to create

Usage

ferry domains connect <DOMAIN>

Arguments

ArgumentDescription
<DOMAIN>Domain name, e.g. example.com

ferry domains verify

Check now whether a domain's DNS points at this server (exit 1 while it doesn't)

Usage

ferry domains verify <DOMAIN>

Arguments

ArgumentDescription
<DOMAIN>Domain name, e.g. example.com

ferry domains default

Make a domain the default one: the domain of the URL services are shown with

Usage

ferry domains default <DOMAIN>

Arguments

ArgumentDescription
<DOMAIN>Domain name, e.g. example.com

ferry domains disconnect

Disconnect a domain from the server: services stop being served under it

Usage

ferry domains disconnect [OPTIONS] <DOMAIN>

Arguments

ArgumentDescription
<DOMAIN>Domain name, e.g. example.com

Options

OptionDescription
-y, --yesDon't ask for confirmation

ferry domains ls

List a service's custom domains

Usage

ferry domains ls <NAME>

Command Alias: list

Arguments

ArgumentDescription
<NAME>Service name or id

ferry domains add

Add a custom domain to a service

Usage

ferry domains add <NAME> <DOMAIN>

Arguments

ArgumentDescription
<NAME>Service name or id
<DOMAIN>Domain name, e.g. app.example.com

ferry domains rm

Remove a custom domain from a service

Usage

ferry domains rm <NAME> <DOMAIN>

Command Alias: remove

Arguments

ArgumentDescription
<NAME>Service name or id
<DOMAIN>Domain name, e.g. app.example.com

ferry certificates

Show the certificate of every hostname the server routes

Usage

ferry certificates

Command Alias: certs

ferry run

Run a one-off job (or trigger a cron job now)

Usage

ferry run [OPTIONS] <NAME> [-- <CMD>...]

Arguments

ArgumentDescription
<NAME>Service name or id
<CMD>Command to run after -- (default for cron jobs: their start command)

Options

OptionDescription
-f, --followStream the job's output until it finishes (exit 1 if it fails)

ferry jobs

List a service's job runs, or cancel one

Usage

ferry jobs [OPTIONS] <NAME>
ferry jobs <COMMAND>

Subcommands

  • ls — List a service's job runs, newest first
  • cancel — Stop a pending or running job run

Arguments

ArgumentDescription
<NAME>Service name or id (lists its job runs)

Options

OptionDescriptionDefault
-n, --limit <N>Maximum number of entries20

ferry jobs ls

List a service's job runs, newest first

Usage

ferry jobs ls [OPTIONS] <NAME>

Command Alias: list

Arguments

ArgumentDescription
<NAME>Service name or id

Options

OptionDescriptionDefault
-n, --limit <N>Maximum number of entries20

ferry jobs cancel

Stop a pending or running job run

Usage

ferry jobs cancel <JOB_ID>

Arguments

ArgumentDescription
<JOB_ID>Job run id (see 'ferry jobs NAME')

ferry db

Manage Postgres and Redis datastores

Usage

ferry db <COMMAND>

Subcommands

  • create — Create a datastore
  • ls — List datastores
  • show — Show a datastore with its connection URLs
  • update — Change a datastore's memory / CPU limits (applied to the running container, no restart)
  • rm — Delete a datastore and its data

ferry db create

Create a datastore

Usage

ferry db create [OPTIONS] <NAME>

Arguments

ArgumentDescription
<NAME>Datastore name (also its hostname on the private network)

Options

OptionDescriptionDefault
--kind <KIND>postgres or redispostgres
--version <V>Major version (default: 16 for postgres, 7 for redis)
--database <NAME>Postgres database name
--user <USER>Postgres user
--memory <SIZE>Memory limit, e.g. 256M or 1G (a plain number is MiB; default: the server's)
--cpu <CPUS>CPU limit, e.g. 0.5, 2 or 500m (default: the server's)
-w, --waitWait until the datastore is available

ferry db ls

List datastores

Usage

ferry db ls

Command Alias: list

ferry db show

Show a datastore with its connection URLs

Usage

ferry db show <NAME>

Arguments

ArgumentDescription
<NAME>Datastore name or id

ferry db update

Change a datastore's memory / CPU limits (applied to the running container, no restart)

Usage

ferry db update <--memory <SIZE>|--cpu <CPUS>> <NAME>

Arguments

ArgumentDescription
<NAME>Datastore name or id

Options

OptionDescription
--memory <SIZE>Memory limit, e.g. 256M or 1G (a plain number is MiB; 'default' = the server's default)
--cpu <CPUS>CPU limit, e.g. 0.5, 2 or 500m ('default' = the server's default)

ferry db rm

Delete a datastore and its data

Usage

ferry db rm [OPTIONS] <NAME>

Command Alias: delete

Arguments

ArgumentDescription
<NAME>Datastore name or id

Options

OptionDescription
-y, --yesDon't ask for confirmation
--forceDelete even if other services still reference it (their next deploy or restart will fail)

ferry env-group

Manage environment groups

Usage

ferry env-group <COMMAND>

Subcommands

  • create — Create an env group, optionally with variables
  • ls — List env groups
  • show — Show an env group's variables and linked services
  • set — Set variables (restarts linked services unless --no-restart)
  • unset — Remove variables (restarts linked services unless --no-restart)
  • rm — Delete an env group
  • link — Link an env group to a service
  • unlink — Unlink an env group from a service

ferry env-group create

Create an env group, optionally with variables

Usage

ferry env-group create <NAME> [KEY=VALUE]...

Arguments

ArgumentDescription
<NAME>Group name
<KEY=VALUE>KEY=VALUE pairs

ferry env-group ls

List env groups

Usage

ferry env-group ls

Command Alias: list

ferry env-group show

Show an env group's variables and linked services

Usage

ferry env-group show <NAME>

Arguments

ArgumentDescription
<NAME>Env group name or id

ferry env-group set

Set variables (restarts linked services unless --no-restart)

Usage

ferry env-group set [OPTIONS] <NAME> <KEY=VALUE>...

Arguments

ArgumentDescription
<NAME>Env group name or id
<KEY=VALUE>KEY=VALUE pairs

Options

OptionDescription
--no-restartSave without restarting linked services

ferry env-group unset

Remove variables (restarts linked services unless --no-restart)

Usage

ferry env-group unset [OPTIONS] <NAME> <KEY>...

Arguments

ArgumentDescription
<NAME>Env group name or id
<KEY>Variable names

Options

OptionDescription
--no-restartSave without restarting linked services

ferry env-group rm

Delete an env group

Usage

ferry env-group rm [OPTIONS] <NAME>

Command Alias: delete

Arguments

ArgumentDescription
<NAME>Env group name or id

Options

OptionDescription
-y, --yesDon't ask for confirmation
--forceDelete even if services are still linked to it
--restartWith --force: restart the linked live services so they drop the group's variables

Link an env group to a service

Usage

ferry env-group link <SERVICE> <GROUP>

Arguments

ArgumentDescription
<SERVICE>Service name or id
<GROUP>Env group name or id

Unlink an env group from a service

Usage

ferry env-group unlink <SERVICE> <GROUP>

Arguments

ArgumentDescription
<SERVICE>Service name or id
<GROUP>Env group name or id

ferry blueprint

Apply a ferry.yaml / render.yaml blueprint

Usage

ferry blueprint <COMMAND>

Subcommands

  • apply — Create/update the resources described by a blueprint

ferry blueprint apply

Create/update the resources described by a blueprint

Usage

ferry blueprint apply [OPTIONS] [FILE]

Arguments

ArgumentDescription
<FILE>Blueprint file (default: ./ferry.yaml, then ./render.yaml)

Options

OptionDescription
--dry-runShow what would change without changing anything

ferry open

Print (and try to open) a service's URL

Usage

ferry open <NAME>

Arguments

ArgumentDescription
<NAME>Service name or id

ferry deploy-hook

Show or rotate a service's deploy hook (a secret URL that triggers a deploy)

Usage

ferry deploy-hook <COMMAND>

Subcommands

  • show — Print the deploy hook URL (POST or GET it to deploy)
  • rotate — Replace the hook's secret key and print the new URL (the old URL stops working)

ferry deploy-hook show

Print the deploy hook URL (POST or GET it to deploy)

Usage

ferry deploy-hook show <NAME>

Arguments

ArgumentDescription
<NAME>Service name or id

ferry deploy-hook rotate

Replace the hook's secret key and print the new URL (the old URL stops working)

Usage

ferry deploy-hook rotate [OPTIONS] <NAME>

Arguments

ArgumentDescription
<NAME>Service name or id

Options

OptionDescription
-y, --yesDon't ask for confirmation

On this page