Authentication Required
Skip to content
Lattice Docs Commandline (CLI) reference

latticectl

Introduction

The Lattice Command Line Interface is a tool for managing your lattices via the shell.

Installation

You can download the Lattice CLI from the download page. You can also install it on MacOS using Homebrew:

$ brew install mlab-lattice/lattice/lattice-cli

Once installed, you can view a list of commands by running lattice help.

To use the Lattice CLI, first generate an Access Key ID and Access Key Secret on the Access Keys page. Run lattice lattices to generate a config file. You will be prompted to enter the Access Key ID and Access Key Secret you just generated.

You will now be able to run Lattice CLI commands. Try making a new lattice by running:

$ lattice lattices:create --provider AWS --region us-east-1 --name my-first-lattice

You can then see the status of this lattice by running:

$ lattice lattices:status --lattice my-first-lattice

To learn more about how to get started, see the Getting Started Guide and the Official Lattice Tutorial.

Help

You can view a list of available commands by running lattice help.

To get detailed instructions on specific commands, pass the name of the command to lattice help. For example, to learn more about the usage of systems:create, run lattice help systems:create:

Create a new system

Usage:
  lattice systems:create [flags]

Flags:
      --config string       the config file to use
      --definition string   the repository containing the system definition
  -h, --help                help for systems:create
      --lattice string      the lattice to act on
      --name string         the name of the system to create

You can also append the -h, --help flag to get information on commands.

Output Formats

You can set the output format of lattice commands using the -o, --output flag. The options are table and json. table is the default output format. It is a human readable table that can also easily be used with grep and AWK. For example:

$ lattice lattices

    Name    | Provider |  Region   |                                 Address                                 |  Status
------------|----------|-----------|-------------------------------------------------------------------------|-----------
 production | AWS      | us-east-1 | http://lattice-ed9e558167-master-1366054109.us-east-1.elb.amazonaws.com | succeeded
 staging    | AWS      | us-east-1 | http://lattice-301657cb4c-master-1469449927.us-east-1.elb.amazonaws.com | succeeded

The JSON output will output a JSON object. The JSON objects are easily machine-readable. If you are piping output into another program, we recommend using the JSON output. JSON output can easily be formatted and manipulated using the jq tool. For example:

$ lattice lattices -o json | jq

[
  {
    "id": "ed9e558167a1ba8e39dadaaf85839320",
    "name": "production",
    "provider": "AWS",
    "region": "us-east-1",
    "state": "succeeded",
    "address": "http://lattice-ed9e558167-master-1366054109.us-east-1.elb.amazonaws.com",
    "accountId": "a3ecd193cea9156687d3df744be0e88c",
    "createdAt": "2018-04-11T22:20:25.142Z"
  },
  {
    "id": "301657cb4c6b32691ee1430c8b1174a6",
    "name": "staging",
    "provider": "AWS",
    "region": "us-east-1",
    "state": "succeeded",
    "address": "http://lattice-301657cb4c-master-1469449927.us-east-1.elb.amazonaws.com",
    "accountId": "a3ecd193cea9156687d3df744be0e88c",
    "createdAt": "2018-04-16T19:07:58.689Z"
  }
]

Output Highlighting

Unique identifiers of resources are colored cyan. Note that this may display as a different color depending on your terminal settings.

The Watch Flag

Many commands in the lattice CLI are asynchronous. When you deploy a system using lattice systems:deploy, lattice enqueues the deploy and then the command returns. To watch the progress of commands, use the -w, --watch flag. This will update the status of a command every five seconds. When a command reaches a terminating state (e.g. a success or a failure), the command will exit with the appropriate exit code. Watching operations such as lattice systems:build and lattice systems:deploy will exit when they reach a terminating state. Watching the status of resources, such as lattice systems and lattice services:status will not exit until lattice receives a SIGTERM. See the documentation for commands to learn which commands can terminate when watched.

Config Files

Lattice will generate a config file from your Access Key ID and Access Key Secret. By default this config file is located at ~/.config/lattice/config.json. You can instruct lattice to use a different config file by passing the path of the config file with the --config option.

Context

Rather than including the --lattice and --system flags with every command, you can set the lattice and system you are currently working on in the context. This is useful if you are issuing several commands in a row on the same lattice or system. You can also set a context by running lattice context:set. This will create a context file located at ~/.config/lattice/context.json. You can always override the current context by manually setting the --lattice and/or --system flags.

Usage with AWK

The default table output is easily parsed by awk. For example, the output for lattice lattices:status is:

    Name    | Provider |  Region   |                                 Address                                 |  Status
------------|----------|-----------|-------------------------------------------------------------------------|-----------
 production | AWS      | us-east-1 | http://lattice-ed9e558167-master-1366054109.us-east-1.elb.amazonaws.com | succeeded

Lattice production is stable.

This can be piped to awk using the separator '|'. To pick out the status column, you can use this awk command:

$ lattice lattices:status --lattice production | awk -F '|' 'FNR == 4 {print $5}' | sed 's/ //g'
succeeded

Here we also pipe to sed to trim any whitespace.

The -w, --watch flag with table output is not usable with AWK. Use JSON output with JQ instead.

Usage with JQ

The JSON output with -o, --output json can be piped to the jq tool. JQ is a powerful tool for parsing and manipulating JSON. For example, piping the above output to JQ:

$ lattice lattices:status --lattice timl -o json | jq -r '.[0].state'
succeeded

Using the -w, --watch flag will stream the status every five seconds. The pipe to JQ will remain open and JQ will output the result every 5 seconds.

$ lattice lattices:status --lattice timl -o json -w | jq -r '.[0].state'
succeeded
succeeded
succeeded

Commands

build

Flags:

Name Description
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--path PATH
--system SYSTEM
--version VERSION
--watch, -w

builds

Flags:

Name Description
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--system SYSTEM
--watch, -w

context

Rather than including the --lattice and --system flags with every command, you can set the lattice and system you are currently working on in the context. This is useful if you are issuing several commands in a row on the same lattice or system. The context stores the name of a lattice and/or a system to be passed into the --lattice and --system flags of commands as appropriate. You can always override the current context by manually setting the --lattice and/or --system flags.

Flags:

Name Description
--config CONFIG
--output OUTPUT, -o Set the output format of the command. Valid options: json

Examples:

Without a context you must pass the --lattice and --system flags to the lattice systems deploy command:

$ lattice context get
lattice:
system:

$ lattice systems deploy --version v1.0.0 --lattice my-lattice --system my-system

Deploying version v1.0.0 for system my-system. Deploy ID: babdea1e-fd8e-47e1-a80e-4cd2b65a8822

To watch deploy, run:

    lattice system:deploys:status -w --deploy babdea1e-fd8e-47e1-a80e-4cd2b65a8822

Instead, you can set the context and the --lattice and --system flags are automatically filled in by the context.

$ lattice context set --lattice my-lattice --system my-system
lattice: my-lattice
system: my-system

$ lattice systems deploy --version v2.0.0

Deploying version v1.0.0 for system my-system. Deploy ID: faf615f5-8a8a-4efa-89e5-ee55210dcf84

To watch deploy, run:

    lattice system:deploys:status -w --deploy faf615f5-8a8a-4efa-89e5-ee55210dcf84

Caution

Make sure to check the current context by running lattice context get before running commands. Otherwise you may inadvertently make a change to a lattice or system you did not want to change.

deploy

Flags:

Name Description
--build BUILD
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--path PATH
--system SYSTEM
--version VERSION
--watch, -w

deploys

Flags:

Name Description
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--system SYSTEM
--watch, -w

jobs

Flags:

Name Description
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--system SYSTEM
--watch, -w

secrets

services

Lists the services in a specific system. Will show the service ID, state, number of up-to-date and stale nodes, any public addresses, and extra informational messages.

Flags:

Name Description
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--system SYSTEM
--watch, -w

Examples:

Listing the services in a system named petflix:

$ lattice services --system petflix

   Service    | State  | Updated | Stale |                                        Addresses                                         | Info
--------------|--------|---------|-------|------------------------------------------------------------------------------------------|------
 /petflix/api | stable |       1 |     0 |                                                                                          |
 /petflix/www | stable |       1 |     0 | 8080: http://tf-lb-20180420221715517300000004-996524393.us-east-2.elb.amazonaws.com:8080 |

systems

Shows the systems in a lattice.

Flags:

Name Description
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--watch, -w

Examples:

Examples:

Listing the systems in a lattice:

$ lattice systems --lattice my-lattice

  Name   |                     Definition                      | Status
---------|-----------------------------------------------------|--------
 petflix | https://github.com/mlab-lattice/system__petflix.git | stable

teardown

Flags:

Name Description
--system SYSTEM (required)
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--watch, -w

teardowns

Flags:

Name Description
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--system SYSTEM
--watch, -w

builds logs

Flags:

Name Description
--build BUILD (required)
--path PATH (required)
--config CONFIG
--context CONTEXT
--follow
--previous
--sidecar SIDECAR
--since SINCE
--system SYSTEM
--tail TAIL
--timestamps

builds status

Flags:

Name Description
--build BUILD (required)
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--system SYSTEM
--watch, -w

context create

Flags:

Name Description
--name NAME (required)
--url URL (required)
--bearer-token BEARER-TOKEN
--config CONFIG
--system SYSTEM
--unauthenticated

context delete

Flags:

Name Description
--name NAME (required)
--config CONFIG

context list

Flags:

Name Description
--config CONFIG
--output OUTPUT, -o Set the output format of the command. Valid options: json

context switch

Flags:

Name Description
--config CONFIG
--name NAME
--none

context update

Flags:

Name Description
--bearer-token BEARER-TOKEN
--config CONFIG
--name NAME
--system SYSTEM
--unauthenticated
--url URL

deploys status

Flags:

Name Description
--deploy DEPLOY (required)
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--system SYSTEM
--watch, -w

jobs logs

Flags:

Name Description
--job JOB (required)
--config CONFIG
--context CONTEXT
--follow
--previous
--sidecar SIDECAR
--since SINCE
--system SYSTEM
--tail TAIL
--timestamps

jobs run

Flags:

Name Description
--path PATH (required)
--config CONFIG
--context CONTEXT
--env ENV, -e
--follow
--secret SECRET
--system SYSTEM

jobs status

Flags:

Name Description
--job JOB (required)
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--system SYSTEM
--watch, -w

secrets get

Flags:

Name Description
--secret SECRET (required)
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--system SYSTEM

secrets set

Flags:

Name Description
--secret SECRET (required)
--config CONFIG
--context CONTEXT
--file FILE
--system SYSTEM
--value VALUE

secrets unset

Flags:

Name Description
--secret SECRET (required)
--config CONFIG
--context CONTEXT
--system SYSTEM

services logs

Flags:

Name Description
--config CONFIG
--context CONTEXT
--follow
--instance INSTANCE
--path PATH
--previous
--service SERVICE
--sidecar SIDECAR
--since SINCE
--system SYSTEM
--tail TAIL
--timestamps

services status

Will show the service ID, state, number of up-to-date and stale nodes, any public addresses, and extra informational messages.

Flags:

Name Description
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--path PATH
--service SERVICE
--system SYSTEM
--watch, -w

Examples:

Show the information for a service named /petflix/www in a system named petflix:

$ lattice services --system petflix --service /petflix/www

   Service    | State  | Updated | Stale |                                        Addresses                                         | Info
--------------|--------|---------|-------|------------------------------------------------------------------------------------------|------
 /petflix/www | stable |       1 |     0 | 8080: http://tf-lb-20180420221715517300000004-996524393.us-east-2.elb.amazonaws.com:8080 |

systems create

Create a new system in a lattice. Provide a name for the system and a git repository URL (ending in .git) where the system definition resides. This system definition repository will be used to build and deploy versions of the system based on the git tags of the repository.

Flags:

Name Description
--definition DEFINITION (required)
--name NAME (required)
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--watch, -w

Examples:

Creating a system named my-system with a system definition residing at https://github.com/mlab-lattice/system__petflix.git:

$ lattice systems:create --name my-system --definition https://github.com/mlab-lattice/system__petflix.git
System my-system created. To rollout a version of this system run:

    lattice systems:deploy --system my-system --version <tag>

systems delete

Deletes a system from a lattice. This command will not run if a version of the system is currently deployed. You must explicitly teardown the system before deleting. A teardown will deprovision the services in an system. Once there are no running services in a system, the system can then be deleted.

If you want to teardown a deploy, but intend to deploy a new version at a later date, just teardown the system without delting.

Flags:

Name Description
--system SYSTEM (required)
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--watch, -w

Examples:

Teardown and then delete a system:

$ lattice systems:teardown --system petflix

Tearing down system petflix. Teardown ID: 15c77128-e7a0-4dbe-838b-60ebfab0a358

To watch teardown, run:

    lattice system:teardowns:status -w --teardown 15c77128-e7a0-4dbe-838b-60ebfab0a358

$ lattice systems:delete --system petflix
System petflix deleted.

Attempting to delete a system without first tearing down the system:

TODO: Doesn't work

systems status

Show information about a system. This shows the health and information about the services in a system.

Flags:

Name Description
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--system SYSTEM
--watch, -w

Examples:

Show information about a system:

$ lattice systems:status

   Service    | State  | Updated | Stale |                                        Addresses                                         | Info
--------------|--------|---------|-------|------------------------------------------------------------------------------------------|------
 /petflix/api | stable |       1 |     0 |                                                                                          |
 /petflix/www | stable |       1 |     0 | 8080: http://tf-lb-20180424220446719300000003-421405457.us-east-2.elb.amazonaws.com:8080 |

systems versions

Show the available versions in of a system. These are the tags of a system definition repo that can be deployed.

Flags:

Name Description
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json
--system SYSTEM

Examples:

List system versions:

TODO: Not working

teardowns status

Flags:

Name Description
--teardown TEARDOWN (required)
--config CONFIG
--context CONTEXT
--output OUTPUT, -o Set the output format of the command. Valid options: json, table
--system SYSTEM
--watch, -w