CLI Specification

Using the command line interface

This document is intended for a developer creating new DC/OS CLI subcommands. See also Universe Getting Started.

The DC/OS command-line interface (CLI) is a utility to manage cluster nodes, install and manage packages, inspect the cluster state, and manage services and tasks. The DC/OS CLI is open and extensible: anyone can create a new subcommand and make it available for installation by end users. For example, the Spark DC/OS service provides CLI extensions for working with Spark. When installed, you can type the following command to submit Spark jobs and query their status:

dcos spark [<flags>] <command>

How the DC/OS CLI discovers subcommands

When you run the dcos command, it searches the current shell’s PATH for executables with names that are prefixed with dcos- in the ~/.dcos/clusters/<cluster_id>/subcommands/<package_name>/env/bin directory.

Installing a CLI subcommand

To install a CLI subcommand, run:

dcos package install <package>

or

dcos package install <package> --cli

The same packaging format and repository is used for both DC/OS services and CLI subcommands.

IMPORTANT: CLI modules are cluster specific and stored in ~/.dcos/clusters/"cluster_id"/subcommands. You must install a CLI module for each cluster. For example, if you connect to cluster 1 and install the Spark module, then connect to cluster 2, which is also running Spark. Spark CLI commands are not available until you install the module for that cluster.

Creating a DC/OS CLI subcommand

Requirements

  • Executables for Mac, Linux, and Windows

Standard flags

You must assign a standard set of flags to each DC/OS CLI subcommand, described below:

--info
--help
-h

–info

The --info flag shows a short, one-line description of the function of your subcommand. This content is displayed when the user runs dcos help.

Example from the Spark CLI:
dcos spark --info
Spark DC/OS CLI Module

When you run the dcos command without parameters, the info is returned for each subcommand:

dcos | grep spark
      spark        Spark DC/OS CLI Module

–help and -h

The --help and -h flags both show the detailed usage for your subcommand.

Example from the Marathon CLI:

dcos marathon --help
Description:
    Deploy and manage applications to DC/OS.
...

Subcommand naming conventions

The DC/OS CLI subcommand naming convention is:

dcos <subcommand> <resource> <verb>

A resource is typically a noun and verb is an action supported by the resource. For example, in the following command, resource is app and the action is add:

dcos marathon app add

Subcommand logging

The environment variable DCOS_LOG_LEVEL is set to the log level the user sets at the command line.

The logging levels are described in Python’s logging HOWTO: DEBUG, INFO, WARNING, ERROR and CRITICAL.

Packaging a CLI subcommand

To make your subcommand available to end users:

  1. Add a package entry to the Mesosphere Universe repository. See the Universe README for the specification.

The package entry must contain a file named resource.json that contains links to the executable subcommands.

When you run dcos package install <package> --cli:

  1. The package entry for is retrieved from the repository.
  2. The resource.json file is parsed to find the CLI resources.
  3. The executable for the user’s platform is downloaded.

The DC/OS CLI module

The DC/OS CLI module has a set of tools useful to subcommand developers.

Example: Hello World subcommand

The Hello World example implements a new subcommand called helloworld:

dcos package install helloworld --cli
dcos helloworld