CLI Specification

Using the command line interface

This document is intended for a developer creating new DC/OS™ CLI subcommands. See also Catalog 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® 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 Catalog repository. See the Catalog 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:

  2. The package entry for <package> is retrieved from the repository.

  3. The resource.json file is parsed to find the CLI resources.

  4. 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