Skip to content
CLI utility to talk to
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


CLI utility to talk to

The main use case is to call this utility from the build automation (CI) tool that already builds your application and let Stacksmith build cloud images for you.


You can fetch a binary for your platform via the Github releases page. For example, on linux:

  wget -O /tmp/stacksmith
  sudo install /tmp/stacksmith /usr/local/bin/stacksmith

The stacksmith CLI is also available as a docker image:

docker run -ti

First steps

  1. Sign up to and pick a project
  2. Use stacksmith init to create a Stackerfile.yml file pointing to your app and your local build artifacts to upload
  3. Run stacksmith build

See full example in using Travis CI.


You can learn about the possible fields of the Stackerfile.yml file in its reference documentation.

Furthermore, the CLI tool offers inline documentation for commands and topics:

$ stacksmith help
$ stacksmith help build

Common topics will be presented in this README.

Configuring CI authorization

If you need to run stacksmith build on another machine, e.g. as part of an automated build job, you obviously cannot rely on the interactive stacksmith auth login tool on the server.

You can generate and export a token for such purposes by following these instructions:

  1. Make sure you have a working account on

  2. Download the stacksmith client (see the release page) for your platform and authenticate. This command will open a browser window which might ask you to log-in into stacksmith if you haven't already:

stacksmith auth login
  1. Generate a new access token. You can add a description to your newly created token so you can later manage your access tokens more easily:
stacksmith auth access-tokens create --description my-CI-integration
  1. Copy&paste the output of the previous command (the long string starting with MDAxOGxvY2F0aW9uI...) into a secret env var, e.g. STACKSMITH_ACCESS_TOKEN on your CI system.

Consuming build results

The stacksmith CLI utility will output the build logs to stderr and, in case of success, a Build Spec JSON object on stdout.

The Build Spec JSON object contains, among other things, pointers to the build results, such as the AMI ID or the docker image name or the deployment template URL.

Here's an example that shows how to perform a build and retrieve the Helm chart generated by Stacksmith:

$ stacksmith build | tee image_spec.json
$ stacksmith get template -s image_spec.json -o my-helm-chat.tgz

The Build Spec also contains a snapshot of all the installed packages. You may want to instruct your CI system to archive this file along with your build artifacts for future reference.

Using arbitrary base images

You can specify a base image for each platform. E.g. this shows how to use a custom AMI:

    amiId: "ami-4bf3d731"

Each distribution might have a different convention w.r.t the default username. Amazon linux and RHEL use ec2-user, but some other distributions use other usernames.

For example here is how to use a Ubuntu base image:

    amiId: "ami-0a313d6098716f372"
    sshUsername: ubuntu

Defining a multi-image application

You can specify multiple images to build for a single application. Each will be built separately, and then the deployment template will be able to reference each of the images.

Notes: This currently only works for AWS AMI builds. Other targets will be available soon.

In order to specify multiple images use the images: key, passing an array of image descriptions.

  - name: "mariadb"
  - name: "app"

In addition you will need to specify a deployment template so that you can reference each of the images.

  aws: cf.json

See the stacksmith docs for how to provide a custom deployment template.

You can’t perform that action at this time.