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 <command>
corresponds to a Docker command, and <target>
either is a single container or
a group.
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 database
first, then run web
(recreating 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 --extend
If you want to exclude a container or a whole group from a Crane command, you
can specify this with --exclude <reference>
(or via CRANE_EXCLUDE
). The
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 up
/lift
or 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.
ip
, ip6
, publish
, publish-all
and detach
disabled, and rm
enabled.
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.