Crane is a very light wrapper around the Docker CLI. This means that most
commands just call the corresponding Docker command, but for all targeted
services. The basic format is
crane <command> <target>, where
corresponds to a Docker command, and
<target> either is a single container or
When executing commands, keep the following 2 rules in mind:
As an example, imagine you have a container
web depending on container
database. When you execute
crane run web, then Crane will start
first, then run
web if it already exists).
usage: crane [<flags>] <command> [<args> ...] Lift containers with ease - https://michaelsauter.github.io/crane Flags: --help Show context-sensitive help (also try --help-long and --help-man). -v, --verbose Enable verbose output. --dry-run Dry run (implicitly verbose; no side effects). -c, --config=~/crane.yml ... Location of config file(s). -p, --prefix=PREFIX Container/Network/Volume prefix. -x, --exclude=container|group ... Exclude group or container (repeatable). -o, --only=container|group Limit scope to group or container. -e, --extend Extend command from target to dependencies. --tag=TAG Override image tags. Commands: help [<command>...] Show help. up [<flags>] [<target>] [<cmd>...] Build or pull images if they don't exist, then run or start the containers. Alias of `lift`. -n, --no-cache Build the image(s) without any cache. -l, --parallel=1 Define how many containers are provisioned in parallel. -d, --detach Detach from targeted container. lift [<flags>] [<target>] [<cmd>...] Build or pull images if they don't exist, then run or start the containers. Alias of `up`. -n, --no-cache Build the image(s) without any cache. -l, --parallel=1 Define how many containers are provisioned in parallel. -d, --detach Detach from targeted container. run [<flags>] [<target>] [<cmd>...] Run containers. Already existing containers will be removed first. -d, --detach Detach from container. create [<target>] [<cmd>...] Create containers. Already existing containers will be removed first. start [<target>] Start stopped containers. Non-existant containers will be created. stop [<target>] Stop running containers. kill [<target>] Kill running containers. exec [<flags>] [<target>] [<cmd>...] Execute command in the targeted container(s). Stopped containers will be started, non-existant containers will be created first. --privileged Give extended privileges to the process. --user=USER Run the command as this user. rm [<flags>] [<target>] Remove stopped containers. -f, --force Remove running containers, too. --volumes Remove volumes as well. pause [<target>] Pause running containers. unpause [<target>] Unpause paused containers. provision [<flags>] [<target>] Build or pull images. -n, --no-cache Build the image(s) without any cache. -l, --parallel=1 Define how many containers are provisioned in parallel. pull [<target>] Pull images. push [<target>] Push containers to the registry. logs [<flags>] [<target>] Show container logs. -f, --follow Follow log output. --tail=TAIL Define number of lines to display at the end of the logs. -t, --timestamps Show timestamps. -z, --colorize Use different color for each container. --since=SINCE Show logs since timestamp. stats [<flags>] [<target>] Display statistics about containers. -n, --no-stream Disable stats streaming. status [<flags>] [<target>] Display status of containers (similar to `docker ps`). -n, --no-trunc Don't truncate output. cmd [<command>] [<arguments>...] Execute predefined shortcut command. generate [<flags>] [<target>] Generate files by passing the config to given template. -t, --template=TEMPLATE Template to use. -O, --output=OUTPUT The file(s) to write the output to. am reset [<target>] Reset accelerated mount. am logs [<flags>] [<target>] Show logs of accelerated mount. -f, --follow Follow log output. version [<flags>] Display the current version.
--verbose. Most options have a short version as well, e.g.
up -n. The CLI provides help for every command, e.g.
crane help run.
By default, Crane will apply the command ONLY to the target. For example, if you have a container
web that depends on a container
db, then executing
crane run web will make sure that
db is started before running
web (recreating it if it already exists). If you want to extend the target - in this example to recreate
db as well if it already exists - you can use
If you want to exclude a container or a whole group from a Crane command, you
can specify this with
--exclude <reference> (or via
flag can be repeated to exclude several services or groups (use a multi-line
environment variable value to pass several references via
CRANE_EXCLUDE). Excluded services' declaration and references in the configuration file
will be completely ignored, so their dependencies will also be excluded
(unless they are also required by other non-excluded services).
Apart from excluding services, it is also possible to limit the target to just
one container or group with
--only (or via
CRANE_ONLY). The flag cannot be
repeated. Containers outside the targets will not be considered by Crane then.
If you append a command to
run, Crane will add a timestamp
to the container name (e.g.
foo will become
foo-1447155694523), making it
possible to have multiple containers based on the same Crane config.
Often you'll want to execute the same command inside a container over and over again. Crane allows to define shortcuts for them in the configuration, which can be executed via
crane cmd. For example, you can define
console: run web bin/rails c inside the
commands section of the configuration to run an ad-hoc
web container with the
rails c command inside by simply executing
crane cmd console from the host. This is effectively the same as running the longer
crane run web bin/rails c.
The shortcuts can be defined as strings or arrays, and may start with any valid Crane subcommand. That means you can use them to run containers, or execute commands inside existing containers etc. The CLI interface accepts further arguments, which are simply appended to the predefined command. It is possible to list available commands by typing just
crane cmd. Some examples:
commands: console: run web bin/rails c server: run web rspec: run web bin/rspec rubocop: run web bin/rubocop psql: exec postgres psql
Usage is simple:
crane cmd console would start a Rails console in the default (development) environment, and using
crane cmd console test would append
test to the predefined command, starting a console in the test environment.