This document is intended for a developer creating new DC/OS CLI commands.
See also the DC/OS Service Specification.
The DC/OS CLI
You can install the DC/OS Command Line Interface (CLI) locally on your machine. The DC/OS CLI communicates with the DC/OS cluster, running either on-premise or with a cloud provider.
The DC/OS CLI uses a single command,
dcos. All functions are expressed as subcommands, and are shown with the
dcos help command:
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 run Spark jobs in the datacenter and query their status:
$ dcos spark [parameters]
How to create a new DC/OS CLI subcommand
DC/OS CLI subcommands:
- executables specified for Mac, Linux, and Windows
Example: Hello World
The Hello World example implements a new subcommand called helloworld:
$ dcos package install helloworld --cli
$ dcos helloworld
How the DC/OS CLI discovers subcommands
dcos command is run, it searches the current shell’s PATH for executables with names that are prefixed with
dcos- in the
In the Hello World example, written in Python, you can create an executable of the subcommand using pyinstaller.
DC/OS CLI configuration
The DC/OS CLI maintains a configuration file in TOML format, where subcommands can store configuration data.
The environment variable
DCOS_CONFIG contains the path to this file.
Example of a configuration file:
host = "localhost"
port = "8080"
sources = [ "git://github.com/mesosphere/universe.git", "https://github.com/mesosphere/universe/archive/master.zip",]
cache = "/tmp/dcos-cache"
foo = [ "bar", "baz" ]
You can make changes to the configuration file by using the
dcos config command. For example, to change the marathon.host value:
$ dcos config set marathon.host localhost
You must assign a standard set of flags to each DC/OS CLI subcommand, described below:
--info flag shows a short, one-line description of the function of your subcommand. This content is displayed when the user runs
Example from the Spark CLI:
$ dcos spark --info
Run and manage Spark jobs
$ dcos help | grep spark
spark Run and manage Spark jobs
--version flag shows the version of the subcommand package. Notice that the subcommand package is unrelated to the version of the Service running on DC/OS.
For example, Spark v1.2.1 might be installed on DC/OS, whereas the local spark DC/OS CLI package might be at v0.1.0.
An example from the Marathon CLI:
$ dcos marathon --version
dcos-marathon version 0.1.0
–help and -h
-h flags both show the detailed usage for your subcommand.
An example from the Marathon CLI:
$ dcos marathon --help
Deploy and manage applications on the DC/OS
dcos marathon --config-schema
dcos marathon --info
dcos marathon app add [<app-resource>]
dcos marathon app list
dcos marathon app remove [--force] <app-id>
dcos marathon app restart [--force] <app-id>
dcos marathon app show [--app-version=<app-version>] <app-id>
dcos marathon app start [--force] <app-id> [<instances>]
dcos marathon app stop [--force] <app-id>
dcos marathon app update [--force] <app-id> [<properties>...]
dcos marathon app version list [--max-count=<max-count>] <app-id>
dcos marathon deployment list [<app-id>]
dcos marathon deployment rollback <deployment-id>
dcos marathon deployment stop <deployment-id>
dcos marathon deployment watch [--max-count=<max-count>]
dcos marathon task list [<app-id>]
dcos marathon task show <task-id>
-h, --help Show this screen
--info Show a short description of this subcommand
--version Show version
<app-id> The application id
<deployment-id> The deployment id
<instances> The number of instances to start
<task-id> The task id
The DC/OS CLI validates configurations set with the
dcos config set command, by comparing them against a JSON Schema that you define.
When your Marathon CLI subcommand is passed the
--config-schema flag, it MUST output a JSON Schema document for its configuration.
Here’s an example from the Marathon CLI:
$ dcos marathon --config-schema
"title": "Marathon hostname or IP address",
"title": "Marathon port",
Parameter naming conventions
The DC/OS CLI commands naming convention is:
dcos <subcommand> <resource> <verb>
A resource is typically a noun. For example:
dcos marathon app add
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.
The DC/OS CLI Module
The DC/OS Python package is a set of common functionality useful to subcommand developers.
To make your subcommand available to end users, you must:
- Add a package entry to the Mesosphere Universe repository. See the Universe README for the specification.
The package entry contains a file named resource.json that contains links to the executable subcommands.
When the end user runs
dcos package install spark --cli:
- The package entry for Spark is retrieved from the repository,
resource.json file is parsed to find the CLI resources
- The executable for the user’s platform is downloaded
How to install a new CLI subcommand
You can install a new CLI subcommand by using this syntax:
dcos package install <cli package> --cli
The same packaging format and repository is used for both DC/OS Services and CLI subcommands.