§ Command Line Interface

To list available commands, run flynn help.

§ Installation

On OS X and Linux, run this command in a terminal:

L=/usr/local/bin/flynn && curl -sSL -A "`uname -sp`" https://dl.flynn.io/cli | zcat >$L && chmod +x $L

On Windows, run this command in PowerShell:

(New-Object Net.WebClient).DownloadString('https://dl.flynn.io/cli.ps1') | iex

The CLI is securely updated automatically in the background during use.

§ Adding Clusters

When a cluster is bootstrapped, an authentication key and self-signed certificate are created. Flynn will provide a pin for certificate, which must be passed to the Flynn CLI tool with the key to add a cluster.

flynn cluster add -p <tls pin> <cluster name> <controller domain> <controller key>

Example:

flynn cluster add -p KGCENkp53YF5OvOKkZIry71+czFRkSw2ZdMszZ/0ljs= production https://controller.dev.localflynn.com e09dc5301d72be755a3d666f617c4600

These values can be found in ~/.flynnrc if you need to add the cluster on another computer and don’t have the output from installation available.

§ Global Flags

The CLI will try to automatically determine which cluster and app to use by looking at the git remotes for the current directory. If multiple remotes are specified or there are no Flynn git remotes configured, the app must be specified with the global -a flag.

flynn -a myapp ps

If there are multiple Flynn git remotes configured in the current directory, the remote name can be specified, which will select the app and cluster associated with the remote.

To choose a specific cluster when using the CLI, use the global -c flag:

flynn -c production apps

§ apps

§ usage

flynn apps

List all apps.

§ Examples

$ flynn apps
ID                                NAME
f1e85f5392454a329929e3f27f7a5644  gitreceive
4c6325c1f13547059e5496c91a6a97dd  router
8cfd94d040b14bd8aecc086c8f5f5e0d  blobstore
f488cfb478f54edea497bf6347c2eb80  postgres
9d5be7be873c41b9898032c08aa87597  controller

§ cluster

§ usage

flynn cluster
   flynn cluster add [-f] [-d] [--git-url <giturl>] [--no-git] [--docker-push-url <url>] [--docker] [-p <tlspin>] <cluster-name> <domain> <key>
   flynn cluster remove <cluster-name>
   flynn cluster default [<cluster-name>]
   flynn cluster migrate-domain <domain>
   flynn cluster backup [--file <file>]

Manage Flynn clusters.

§ Commands

With no arguments, shows a list of configured clusters.

Command Description
add

Adds <cluster-name> to the ~/.flynnrc configuration file.

Option Description
-f , --force

force add cluster

-d , --default

set as default cluster

--git-url=<giturl>

git URL

--no-git

skip git configuration

--docker-push-url=<url>

Docker push URL

--docker

configure Docker to push to the cluster

-p , --tls-pin=<tlspin>

SHA256 of the cluster’s TLS cert

remove

Removes <cluster-name> from the ~/.flynnrc configuration file.

default

With no arguments, prints the default cluster. With <cluster-name>, sets the default cluster.

migrate-domain

Migrates the cluster’s base domain from the current one to <domain>.

New certificates will be generated for the controller/dashboard and new routes will be added with the pattern <app-name>.<domain> for each app.

backup

Takes a backup of the cluster.

The backup may be restored while creating a new cluster with ‘flynn-host bootstrap –from-backup’.

Option Description
--file=<backup-file>

file to write backup to (defaults to stdout)

§ Examples

$ flynn cluster add -p KGCENkp53YF5OvOKkZIry71+czFRkSw2ZdMszZ/0ljs= default dev.localflynn.com e09dc5301d72be755a3d666f617c4600
Cluster "default" added.

$ flynn cluster migrate-domain new.example.com
Migrate cluster domain from "example.com" to "new.example.com"? (yes/no): yes
Migrating cluster domain (this can take up to 2m0s)...
Changed cluster domain from "example.com" to "new.example.com"

§ create

§ usage

flynn create [-r <remote>] [-y] [<name>]

Create an application in Flynn.

If a name is not provided, a random name will be generated.

If run from a git repository, a 'flynn' remote will be created or replaced that
allows deploying the application via git.

§ Options

Option Description
-r , --remote=<remote>

Name of git remote to create, empty string for none. [default: flynn]

-y , --yes

Skip the confirmation prompt if the git remote already exists.

§ Examples

$ flynn create
Created turkeys-stupefy-perry

§ delete

§ usage

flynn delete [-y] [-r <remote>]

Delete an app.

If run from a git repository with a 'flynn' remote for the app, it will be
removed.

§ Options

Option Description
-r , --remote=<remote>

Name of git remote to delete, empty string for none. [default: flynn]

-y , --yes

Skip the confirmation prompt.

§ Examples

$ flynn -a turkeys-stupefy-perry delete
Are you sure you want to delete the app "turkeys-stupefy-perry"? (yes/no): yes
Deleted turkeys-stupefy-perry

§ deployment

§ usage

flynn deployment
   flynn deployment timeout [<timeout>]

Manage app deployments

§ Commands

With no arguments, shows a list of deployments

Command Description
timeout

gets or sets the number of seconds to wait for each job to start when deploying

§ Examples

$ flynn deployment
ID                                    STATUS    CREATED             FINISHED
a6d470d6-9638-4d74-ae71-91c3d9887714  running   4 seconds ago
39f8b98b-2aed-40a5-9423-ae174b3fb7a9  complete  16 seconds ago      14 seconds ago
f415ae79-0b41-4a49-bc42-d4f90c5a36c5  failed    About a minute ago  About a minute ago
8901a4ba-8d0a-4c84-a467-bfc095aaa75d  complete  4 minutes ago       4 minutes ago

$ flynn deployment timeout 150

$ flynn deployment timeout
150

§ docker

§ usage

flynn docker set-push-url [<url>]
   flynn docker login
   flynn docker logout
   flynn docker push <image>

Deploy Docker images to a Flynn cluster.

§ Commands

Command Description
set-push-url

set the Docker push URL (defaults to https://docker.$CLUSTER_DOMAIN)

login

run “docker login” against the cluster’s docker-receive app

logout

run “docker logout” against the cluster’s docker-receive app

push

push and release a Docker image to the cluster

§ Example

Assuming you have a Docker image tagged "my-custom-image:v2":

$ flynn docker push my-custom-image:v2
flynn: getting image config with "docker inspect -f {{ json .Config }} my-custom-image:v2"
flynn: tagging Docker image with "docker tag my-custom-image:v2 docker.1.localflynn.com/my-app:latest"
flynn: pushing Docker image with "docker push docker.1.localflynn.com/my-app:latest"
The push refers to a repository [docker.1.localflynn.com/my-app] (len: 1)
a8eb754d1a89: Pushed
...
3059b4820522: Pushed
latest: digest: sha256:1752ca12bbedb99734ca1ba3ec35720768a95ad83b7b6c371fc37a28b98ea351 size: 61216
flynn: image pushed, waiting for artifact creation
flynn: deploying release using artifact URI http://docker-receive.discoverd?name=my-app&id=sha256:1752ca12bbedb99734ca1ba3ec35720768a95ad83b7b6c371fc37a28b98ea351
flynn: image deployed, scale it with 'flynn scale app=N'

§ env

§ usage

flynn env [-t <proc>]
   flynn env set [-t <proc>] <var>=<val>...
   flynn env unset [-t <proc>] <var>...
   flynn env get [-t <proc>] <var>

Manage app environment variables.

§ Options

Option Description
-t , --process-type=<proc>

set or read env for specified process type

§ Commands

With no arguments, shows a list of environment variables.

Command Description
set

sets value of one or more env variables

unset

deletes one or more variables

get

returns the value of variable

§ Examples

$ flynn env set FOO=bar BAZ=foobar
Created release 5058ae7964f74c399a240bdd6e7d1bcb.

$ flynn env
BAZ=foobar
FOO=bar

$ flynn env get -t web FOO
bar

$ flynn env unset FOO
Created release b1bbd9bc76d6436ea2fd245300bce72e.

§ export

§ usage

flynn export [options]

Export application configuration and data.

The application's metadata, deploy strategy, release configuration, slug,
formation, and Postgres database will be exported to a tar file.

§ Options

Option Description
-f , --file=<file>

name of file to export to (defaults to stdout)

-q , --quiet

don’t print progress

§ git-credentials

§ usage

flynn git-credentials <operation

§ import

§ usage

flynn import [options]

Create a new application using exported configuration and data.

The application will be created using the metadata, deploy strategy, release
configuration, slug, formation, and Postgres database from the provided export
file.

§ Options

Option Description
-f , --file=<file>

name of file to import from (defaults to stdin)

-n , --name=<name>

name of app to create (defaults to exported app name)

-q , --quiet

don’t print progress

-r , --routes

import routes

§ info

§ usage

flynn info

Show information for an app.

§ Examples

$ flynn info
=== example
Git URL:  https://git.dev.localflynn.com/example.git
Web URL:  http://example.dev.localflynn.com

$ flynn -a example info
=== example
Git URL:  https://git.dev.localflynn.com/example.git
Web URL:  http://example.dev.localflynn.com

§ install

§ usage

flynn install

Starts server for installer web interface.

§ Examples

$ flynn install

§ kill

§ usage

flynn kill <job>

Kill a job

§ limit

§ usage

flynn limit [-t <proc>]
   flynn limit set <proc> <var>=<val>...

Manage app resource limits.

§ Options

Option Description
-t , --process-type=<proc>

set or read limits for specified process type

§ Commands

With no arguments, shows a list of resource limits.

Command Description
set

sets value of one or more resource limits

§ Examples

$ flynn limit
web:     cpu=1000  max_fd=10000  memory=1GB
worker:  cpu=1000  max_fd=10000  memory=1GB

$ flynn limit set web memory=512MB max_fd=12000 cpu=500
Created release 5058ae7964f74c399a240bdd6e7d1bcb

$ flynn limit
web:     cpu=500   max_fd=12000  memory=512MB
worker:  cpu=1000  max_fd=10000  memory=1GB

$ flynn limit set web memory=256MB
Created release b39fe25d0ea344b6b2af5cf4d6542a80

$ flynn limit
web:     cpu=500   max_fd=12000  memory=256MB
worker:  cpu=1000  max_fd=10000  memory=1GB

§ log

§ usage

flynn log [-f] [-j <id>] [-n <lines>] [-r] [-s] [-t <type>]

Stream log for an app.

§ Options

Option Description
-f , --follow

stream new lines

-j , --job=<id>

filter logs to a specific job ID

-n , --number=<lines>

return at most n lines from the log buffer

-r , --raw-output

output raw log messages with no prefix

-s , --split-stderr

send stderr lines to stderr

-t , --process-type=<type>

filter logs to a specific process type

§ meta

§ usage

flynn meta
   flynn meta set <var>=<val>...
   flynn meta unset <var>...

Manage metadata for an application.

§ Examples

$ flynn meta
KEY  VALUE
foo  bar

$ flynn meta set foo=baz bar=qux

$ flynn meta
KEY  VALUE
foo  baz
bar  qux

$ flynn meta unset foo

$ flynn meta
KEY  VALUE
bar  qux

§ mongodb

§ usage

flynn mongodb mongo [--] [<argument>...]
   flynn mongodb dump [-q] [-f <file>]
   flynn mongodb restore [-q] [-f <file>]

§ Options

Option Description
-f , --file=<file>

name of dump file

-q , --quiet

don’t print progress

§ Commands

Command Description
mongodb

Open a console to a Flynn mongodb database. Any valid arguments to mongo may be provided.

dump

Dump a mongo database. If file is not specified, will dump to stdout.

restore

Restore a database dump. If file is not specified, will restore from stdin.

§ Examples

$ flynn mongodb mongo

$ flynn mongodb mongo -- --eval "db.users.find()"

$ flynn mongodb dump -f db.dump

$ flynn mongodb restore -f db.dump

§ mysql

§ usage

flynn mysql console [--] [<argument>...]
   flynn mysql dump [-q] [-f <file>]
   flynn mysql restore [-q] [-f <file>]

§ Options

Option Description
-f , --file=<file>

name of dump file

-q , --quiet

don’t print progress

§ Commands

Command Description
console

Open a console to a Flynn mysql database. Any valid arguments to mysql may be provided.

dump

Dump a mysql database. If file is not specified, will dump to stdout.

restore

Restore a database dump. If file is not specified, will restore from stdin.

§ Examples

$ flynn mysql console

$ flynn mysql console -- -e "CREATE DATABASE db"

$ flynn mysql dump -f db.dump

$ flynn mysql restore -f db.dump

§ pg

§ usage

flynn pg psql [--] [<argument>...]
   flynn pg dump [-q] [-f <file>]
   flynn pg restore [-q] [-f <file>]

§ Options

Option Description
-f , --file=<file>

name of dump file

-q , --quiet

don’t print progress

§ Commands

Command Description
psql

Open a console to a Flynn postgres database. Any valid arguments to psql may be provided.

dump

Dump a postgres database. If file is not specified, will dump to stdout.

restore

Restore a database dump. If file is not specified, will restore from stdin.

§ Examples

$ flynn pg psql

$ flynn pg psql -- -c "CREATE EXTENSION hstore"

$ flynn pg dump -f db.dump

$ flynn pg restore -f db.dump

§ provider

§ usage

flynn provider
   flynn provider add <name> <url>

Manage resource providers associated with the controller.

§ Commands

With no arguments, displays current providers

Command Description
add

creates a new provider <name> at <url>

§ ps

§ usage

flynn ps [-a]

List flynn jobs.

§ Options

Option Description
-a , --all

Show all jobs (default is running and pending)

§ Example

$ flynn ps
ID                                         TYPE  STATE    CREATED         RELEASE
host-f25797dc-c956-4337-89af-d49eff50f58e  web   up       14 seconds ago  1b1db8ef-ba4d-4314-85c1-d5895a44b27e
6ec25d6e-2985-4807-8e64-02dc23c348bc       web   pending  7 seconds ago   1b1db8ef-ba4d-4314-85c1-d5895a44b27e
ab14754c-73b7-4212-a6d9-73b825587fd2       web   pending  2 seconds ago   1b1db8ef-ba4d-4314-85c1-d5895a44b27e

$ flynn ps --all
ID                                         TYPE  STATE    CREATED             RELEASE
host-d84dc657-83b8-4a62-aab8-ad97bb994761  web   down     2 minutes ago       cd698657-2955-4fa4-bc2f-8714b218a7a2
host-feaff633-a37b-4565-9ade-24bae0cfae03  web   down     About a minute ago  cd698657-2955-4fa4-bc2f-8714b218a7a2
host-e8b4f9be-e422-481f-928c-4c82f0bb5e8b  web   down     About a minute ago  cd698657-2955-4fa4-bc2f-8714b218a7a2
host-95747b4f-fdcd-4c44-ab72-b3d9609668e4  run   down     54 seconds ago      cd698657-2955-4fa4-bc2f-8714b218a7a2
host-cef95d8c-a632-4ae6-8a57-e13cbc24afa9  web   down     25 seconds ago      1b1db8ef-ba4d-4314-85c1-d5895a44b27e
host-ef6249e3-b463-4fea-a7dd-b1302872f821  web   down     20 seconds ago      1b1db8ef-ba4d-4314-85c1-d5895a44b27e
host-f25797dc-c956-4337-89af-d49eff50f58e  web   up       14 seconds ago      1b1db8ef-ba4d-4314-85c1-d5895a44b27e
6ec25d6e-2985-4807-8e64-02dc23c348bc       web   pending  7 seconds ago       1b1db8ef-ba4d-4314-85c1-d5895a44b27e
ab14754c-73b7-4212-a6d9-73b825587fd2       web   pending  2 seconds ago       1b1db8ef-ba4d-4314-85c1-d5895a44b27e

§ redis

§ usage

flynn redis redis-cli [--] [<argument>...]
   flynn redis dump [-q] [-f <file>]
   flynn redis restore [-q] [-f <file>]

§ Options

Option Description
-f , --file=<file>

name of dump file

-q , --quiet

don’t print progress

§ Commands

Command Description
redis-cli

Open a console to a Flynn redis instance. Any valid arguments to redis-cli may be provided.

dump

Dump a redis instance. If file is not specified, will dump to stdout.

restore

Restore a dump. If file is not specified, will restore from stdin.

§ Examples

$ flynn redis redis-cli

$ flynn redis dump -f db.dump

$ flynn redis restore -f db.dump

§ release

§ usage

flynn release [-q|--quiet]
   flynn release add [-t <type>] [-f <file>] <uri>
   flynn release update <file> [<id>] [--clean]
   flynn release show [--json] [<id>]
   flynn release delete [-y] <id>
   flynn release rollback [-y] [<id>]

Manage app releases.

§ Options

Option Description
-q , --quiet

only print release IDs

-t <type>

type of the release. Currently only ‘docker’ is supported. [default: docker]

-f , --file=<file>

release configuration file

--json

print release configuration in JSON format

--clean

update from a clean slate (ignoring prior config)

-y , --yes

skip the confirmation prompt when deleting a release

§ Commands

With no arguments, shows a list of releases associated with the app.

Command Description
add

Create a new release from a Docker image. The optional file argument takes a path to a file containing release configuration in a JSON format. It’s primarily used for specifying the release environment and processes (similar to a Procfile). It can take any of the arguments the controller Release type can take.

show

Show information about a release. Omit the ID to show information about the current release.

update

Update an existing release. Takes a path to a file containing release configuration in a JSON format. It can take any of the arguments the controller Release type can take, and will override existing config with any values set thus. Omit the ID to update the current release.

delete

Delete a release. Any associated file artifacts (e.g. slugs) will also be deleted.

rollback

Rollback to a previous release. Deploys the previous release or specified release ID.

§ Examples

Release an echo server using the flynn/slugbuilder image as a base, running socat.

$ cat config.json
{
    "env": {"MY_VAR": "Hello World, this will be available in all process types."},
    "processes": {
        "echo": {
            "args": ["sh", "-c", "socat -v tcp-l:$PORT,fork exec:/bin/cat"],
            "env": {"ECHO": "This var is specific to the echo process type."},
            "ports": [{"proto": "tcp"}]
        }
    }
}
$ flynn release add -f config.json https://registry.hub.docker.com?name=flynn/slugbuilder&id=15d72b7f573b
Created release 989ce4a8-0088-444c-8379-caddded4b957.

$ flynn release
ID                                Created
989ce4a8-0088-444c-8379-caddded4b957  11 seconds ago

$ flynn release show
ID:             989ce4a8-0088-444c-8379-caddded4b957
Artifact:       docker+https://registry.hub.docker.com?name=flynn/slugbuilder&id=15d72b7f573b
Process Types:  echo
Created At:     2015-05-06 21:58:12.751741 +0000 UTC
ENV[MY_VAR]:    Hello World, this will be available in all process types.

$ cat update.json
{
    "processes": {
        "echo": {
            "omni": true
        }
    }
}
$ flynn release update update.json
Created release 1a270395-8d31-4ec1-953a-0683b4f12635.

$ flynn release delete --yes c6b7f512-ef49-46f7-bb57-dd39e97bfb09
Deleted release c6b7f512-ef49-46f7-bb57-dd39e97bfb09 (deleted 1 files)

§ remote

§ usage

flynn remote add [<remote>] [-y]

Create a git remote that allows deploying the application via git.
If a name for the remote is not provided 'flynn' will be used.

§ Options

Option Description
-y , --yes

Skip the confirmation prompt if the git remote already exists.

§ Examples

$ flynn -a turkeys-stupefy-perry remote add
Created remote flynn with url https://git.dev.localflynn.com/turkeys-stupefy-perry.git

$ flynn -a turkeys-stupefy-perry remote add staging
Created remote staging with url https://git.dev.localflynn.com/turkeys-stupefy-perry.git

§ resource

§ usage

flynn resource
   flynn resource add <provider>
   flynn resource remove <provider> <resource>

Manage resources for the app.

§ Commands

With no arguments, shows a list of resources.

Command Description
add

provisions a new resource for the app using <provider>.

remove

removes the existing <resource> provided by <provider>.

§ route

§ usage

flynn route
   flynn route add http [-s <service>] [-c <tls-cert> -k <tls-key>] [--sticky] [--leader] [--no-leader] <domain>
   flynn route add tcp [-s <service>] [-p <port>] [--leader]
   flynn route update <id> [-s <service>] [-c <tls-cert> -k <tls-key>] [--sticky] [--no-sticky] [--leader] [--no-leader]
   flynn route remove <id>

Manage routes for application.

§ Options

Option Description
-s , --service=<service>

service name to route domain to (defaults to APPNAME-web)

-c , --tls-cert=<tls-cert>

path to PEM encoded certificate for TLS, - for stdin (http only)

-k , --tls-key=<tls-key>

path to PEM encoded private key for TLS, - for stdin (http only)

--sticky

enable cookie-based sticky routing (http only)

--no-sticky

disable cookie-based sticky routing (update http only)

--leader

enable leader-only routing mode

--no-leader

disable leader-only routing mode (update only)

-p , --port=<port>

port to accept traffic on (tcp only)

§ Commands

With no arguments, shows a list of routes.

Command Description
add

adds a route to an app

remove

removes a route

§ Examples

$ flynn route add http example.com

$ flynn route add http example.com/path/

$ flynn route add tcp

$ flynn route add tcp --leader

§ run

§ usage

flynn run [-d] [-r <release>] [-e <entrypoint>] [-l] [--] <command> [<argument>...]

Run a job.

§ Options

Option Description
-d , --detached

run job without connecting io streams (implies –enable-log)

-r <release>

id of release to run (defaults to current app release)

-e <entrypoint>

[DEPRECATED] overwrite the default entrypoint of the release’s image

-l , --enable-log

send output to log streams

§ scale

§ usage

flynn scale [options] [<type>=<spec>...]

Scale changes the number of jobs and tags for each process type in a release.

Process type scale should be formatted like TYPE=COUNT[,KEY=VAL...], for example:

web=1                  # 1 web process
web=3                  # 3 web processes, distributed amongst all hosts
web=3,active=true      # 3 web processes, distributed amongst hosts tagged active=true
db=3,disk=ssd,mem=high # 3 db processes, distributed amongst hosts tagged with
                   # both disk=ssd and mem=high

Ommitting the arguments will show the current scale.

§ Options

Option Description
-n , --no-wait

don’t wait for the scaling events to happen

-r , --release=<release>

id of release to scale (defaults to current app release)

-a , --all

show non-zero formations from all releases (only works when listing formations, can’t be combined with –release)

§ Example

$ flynn scale
web=4 worker=2

$ flynn scale --all
496d6e74-9db9-4cff-bcce-a3b44015907a (current)
web=1 worker=2

632cd907-85ab-4e53-90d0-84635650ec9a
web=2

$ flynn scale web=2 worker=5
scaling web: 4=>2, worker: 2=>5

02:28:34.333 ==> web flynn-3f656af6f1e44092aa7037046236b203 down
02:28:34.466 ==> web flynn-ee83def0b8e4455793a43c8c70f5b34e down
02:28:35.479 ==> worker flynn-84f70ca18c9641ef83a178a19db867a3 up
02:28:36.508 ==> worker flynn-a3de8c326cc542aa89235e53ba304260 up
02:28:37.601 ==> worker flynn-e24760c511af4733b01ed5b98aa54647 up

scale completed in 3.944629056s

§ version

§ usage

flynn version

Show flynn version string.