name: "cage"
global_settings:
- "VersionlessSubcommands"
- "ColoredHelp"
settings:
- "SubcommandRequiredElseHelp"
args:
- project-name:
short: "p"
long: "project-name"
value_name: "PROJECT_NAME"
help: "The name of this project. Defaults to the current directory name."
- target:
long: "target"
value_name: "TARGET"
help: "Override settings with values from the specified subdirectory of `pods/targets`. Defaults to `development` unless running tests."
- default-tags:
long: "default-tags"
value_name: "TAG_FILE"
help: "A list of tagged image names, one per line, to be used as defaults for images."
about: "Develop complex projects with lots of Docker services"
after_help: |
To create a new project:
cage new myproj
From inside a project directory:
cage pull # Download images for the a project
cage up --init # Start the app, initializing the database
cage status # Get an overview of the project
Access your application at http://localhost:3000/. To download and edit
the source code for your application, run:
cage source ls # List available service source code
cage source mount rails_hello # Clone source and configure mounts
cage up # Restart any affected services
cage status # See how things have changed
Now create `src/rails_hello/public/index.html` and reload in your browser.
Cage is copyright 2016 by Faraday, Inc., and distributed under either the
Apache 2.0 or MIT license. For more information, see
https://github.com/faradayio/cage.
subcommands:
- sysinfo:
about: "Print information about the system"
hidden: true
- new:
about: "Create a directory containing a new project"
args:
- NAME:
value_name: "NAME"
required: true
help: "The name of the new project"
- status:
about: "Print out the status of the current project"
args:
- POD_OR_SERVICE: &pod_or_service
value_name: "POD_OR_SERVICE"
multiple: true
help: "Pod or service names. Defaults to all."
- build:
about: "Build images for the containers associated with this project"
args:
- POD_OR_SERVICE: *pod_or_service
- pull:
about: "Build images for the containers associated with this project"
args:
- quiet:
long: "quiet"
short: "q"
help: "Don't show download progress"
- POD_OR_SERVICE: *pod_or_service
- up:
about: "Run project"
args:
- init:
long: "init"
help: "Run any pod initialization commands (for first startup)"
- POD_OR_SERVICE: *pod_or_service
- restart:
about: "Restart all services associated with this project"
args:
- POD_OR_SERVICE: *pod_or_service
- stop:
about: "Stop all containers associated with this project"
args:
- POD_OR_SERVICE: *pod_or_service
- rm:
about: "Remove the containers associated with a pod or service"
args:
- force:
short: "f"
long: "force"
help: "Remove without confirming first"
- remove-volumes:
short: "v"
help: "Remove anonymous volumes associated with containers"
- POD_OR_SERVICE: *pod_or_service
- run:
about: "Run a specific pod as a one-shot task"
settings:
- "TrailingVarArg"
args:
- detached: &detached
short: "d"
help: "Run command detached in background"
- user: &user
long: "user"
value_name: "USER"
help: "User as which to run a command"
- no-allocate-tty: ¬ty
short: "T"
help: "Do not allocate a TTY when running a command"
- entrypoint: &entrypoint
long: "entrypoint"
value_name: "ENTRYPOINT"
help: "Override the entrypoint of the service"
- environment: &environment
short: "e"
value_names: ["KEY", "VAL"]
multiple: true
number_of_values: 2
value_delimiter: "="
help: "Set an environment variable in the container"
- SERVICE: &service
value_name: "SERVICE"
required: true
help: "The name of the service, either as `pod/service`, or as just `service` if unique"
- COMMAND: &command
value_name: "COMMAND"
required: false
multiple: true
help: "The command to run, with any arguments"
- run-script:
about: "Run a named script defined in metadata for specified pods or services"
args:
- no-deps: &nodeps
long: "--no-deps"
help: "Do not start linked services when running scripts"
- SCRIPT_NAME:
value_name: "SCRIPT_NAME"
required: true
help: "The named script to run"
- POD_OR_SERVICE: *pod_or_service
- exec:
about: "Run a command inside an existing container"
settings:
- "TrailingVarArg"
args:
- detached: *detached
- user: *user
- no-allocate-tty: *notty
- privileged: &privileged
long: "privileged"
help: "Run a command with elevated privileges"
- SERVICE: *service
- COMMAND:
value_name: "COMMAND"
required: true
multiple: true
help: "The command to run, with any arguments"
- shell:
about: "Run an interactive shell inside a running container"
args:
- detached: *detached
- user: *user
- no-allocate-tty: *notty
- privileged: *privileged
- SERVICE: *service
- test:
about: "Run the tests associated with a service, if any"
settings:
- "TrailingVarArg"
args:
- export-test-output:
long: "--export-test-output"
help: "Copy container's $WORKDIR/test_output to $PROJECT_DIR/test_output"
- SERVICE: *service
- COMMAND: *command
after_help: |
To enable tests for a service, add a label with the test command.
Assuming your service uses rspec, this might look like:
myservice:
labels:
io.fdy.cage.test: "rspec"
Run this test command using:
cage test myservice
To run only a subset of your tests, you can also pass a custom test
command:
cage test myservice rspec spec/my_new_feature_spec.rb
- logs:
about: "Display logs for a service"
args:
- follow:
short: "f"
help: "Follow log output"
- number:
long: "tail"
value_name: "NUMBER"
help: "Number of lines from end of output to display"
- POD_OR_SERVICE: *pod_or_service
- source:
about: "Commands for working with git repositories and local source trees"
settings:
- "SubcommandRequiredElseHelp"
subcommands:
- ls:
about: "List all known source tree aliases and URLs"
- clone:
about: "Clone a git repository using its short alias and mount it into the containers that use it"
args:
- ALIAS:
value_name: "ALIAS"
required: true
help: "The short alias of the repo to clone (see `source list`)"
- mount:
about: "Mount a source tree into the containers that use it"
args: &mount_args
- ALIASES:
value_name: "ALIASES"
multiple: true
min_values: 1
help: "The short aliases of the source trees to operate on (see `source list`)"
- ALL:
long: "all"
short: "a"
help: "Operate on all source trees"
groups: &mount_groups
- sources:
args:
- ALIASES
- ALL
required: true
- unmount:
about: "Unmount a local source tree from all containers"
args: *mount_args
groups: *mount_groups
- generate:
about: "Commands for generating new source files"
settings:
- "SubcommandRequiredElseHelp"
subcommands:
- completion:
about: "Generate shell autocompletion support"
args:
- SHELL:
value_name: "SHELL"
possible_values:
- "bash"
- "fish"
required: true
help: "The name of shell for which to generate an autocompletion script"
after_help: |
To set up shell auto-completion for bash:
cage generate completion bash
source cage.bash-completion
And set up your ~/.profile or ~/.bash_profile to source this file on
each login.
To set up shell auto-completion for fish:
cage generate completion fish
source cage.fish
mkdir -p ~/.config/fish/completions
mv cage.fish ~/.config/fish/completions
- secrets:
about: "Generate config/secrets.yml for local secret storage"
- vault:
about: "Generate config/vault.yml for fetching secrets from vault"
- export:
about: "Export project as flattened *.yml files"
args:
- DIR:
value_name: "DIR"
required: true
help: "The name of the directory to create"