diff --git a/.gitignore b/.gitignore index 8380419..9836566 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,4 @@ pydoc/_build/ Vagrantfile .vagrant +.idea diff --git a/cli/dcoscli/common.py b/cli/dcoscli/common.py index db0f3c1..e3048ac 100644 --- a/cli/dcoscli/common.py +++ b/cli/dcoscli/common.py @@ -26,3 +26,14 @@ def exec_command(cmd, env=None, stdin=None): for std_stream in process.communicate()] return (process.returncode, stdout, stderr) + + +def command_info(doc): + """Get description from doc text + :param doc: command help text + :type doc: str + :returns: one line description of command + :rtype: str + """ + + return doc.split('\n')[1].strip(".").lstrip() diff --git a/cli/dcoscli/config/main.py b/cli/dcoscli/config/main.py index 66d1eed..2dce239 100644 --- a/cli/dcoscli/config/main.py +++ b/cli/dcoscli/config/main.py @@ -6,6 +6,7 @@ import pkg_resources from dcos import cmds, config, emitting, http, util from dcos.errors import DCOSException from dcoscli import analytics +from dcoscli.common import command_info from dcoscli.main import decorate_docopt_usage emitter = emitting.FlatEmitter() @@ -84,7 +85,7 @@ def _info(info): :rtype: int """ - emitter.publish(_doc().split('\n')[0]) + emitter.publish(command_info(_doc())) return 0 diff --git a/cli/dcoscli/data/help/config.txt b/cli/dcoscli/data/help/config.txt index 63b5ee7..73d097f 100644 --- a/cli/dcoscli/data/help/config.txt +++ b/cli/dcoscli/data/help/config.txt @@ -1,4 +1,5 @@ -Get and set DCOS CLI configuration properties +Description: + Manage the DCOS configuration file. Usage: dcos config --info @@ -7,11 +8,26 @@ Usage: dcos config unset dcos config validate +Commands: + set + Add or set a DCOS configuration property. + show + Print the DCOS configuration file contents. + unset + Remove a property from the configuration file. + validate + Validate changes to the configuration file. + Options: - -h, --help Show this screen - --info Show a short description of this subcommand - --version Show version + -h, --help + Print usage. + --info + Print a short description of this subcommand. + --version + Print version information. Positional Arguments: - The name of the property - The value of the property + + The name of the property. + + The value of the property. diff --git a/cli/dcoscli/data/help/dcos.txt b/cli/dcoscli/data/help/dcos.txt index ea70dd7..20869c3 100644 --- a/cli/dcoscli/data/help/dcos.txt +++ b/cli/dcoscli/data/help/dcos.txt @@ -1,39 +1,39 @@ -Command line utility for the Mesosphere Datacenter Operating -System (DCOS) - -'dcos help' lists all available subcommands. See 'dcos --help' -to read about a specific subcommand. +Description: + The Mesosphere Datacenter Operating System (DCOS) spans all of the machines in +your datacenter or cloud and treats them as a single, shared set of resources. Usage: dcos [options] [] [...] Options: - --help Show this screen - --version Show version - --log-level= If set then print supplementary messages to - stderr at or above this level. The severity - levels in the order of severity are: debug, - info, warning, error, and critical. E.g. - Setting the option to warning will print - warning, error and critical messages to stderr. - Note: that this does not affect the output sent - to stdout by the command. - --debug If set then enable further debug messages which - are sent to stdout. + --debug + Enable debug mode. + --help + Print usage. + --log-level= + Set the logging level. This setting does not affect the output sent to + stdout. The severity levels are: + The severity level: + * debug Prints all messages. + * info Prints informational, warning, error, and critical messages. + * warning Prints warning, error, and critical messages. + * error Prints error and critical messages. + * critical Prints only critical messages to stderr. + --version + Print version information Environment Variables: - DCOS_LOG_LEVEL If set then it specifies that message should be - printed to stderr at or above this level. See - the --log-level option for details. - - DCOS_CONFIG This environment variable points to the - location of the DCOS configuration file. - [default: ~/.dcos/dcos.toml] - - DCOS_DEBUG If set then enable further debug messages which - are sent to stdout. - - DCOS_SSL_VERIFY If set, specifies whether to verify SSL certs - for HTTPS, or the path to the certificate(s). - Can also be configured by setting - `core.ssl_config` in the config. + DCOS_CONFIG + Set the path to the DCOS configuration file. By default, this variable + is set to ~/.dcos/dcos.toml. + DCOS_DEBUG + Indicates whether to print additional debug messages to stdout. By + default this is set to false. + DCOS_LOG_LEVEL + Prints log messages to stderr at or above the level indicated. This is + equivalent to the --log-level command-line option. + DCOS_SSL_VERIFY + Indicates whether to verify SSL certificates for HTTPS (true) or set the + path to the SSL certificates (false). By default, this is variable is + set to true. This is equivalent to setting the `core.ssl_config` option + in the DCOS configuration file. diff --git a/cli/dcoscli/data/help/help.txt b/cli/dcoscli/data/help/help.txt index 8f3b8b9..fa49396 100644 --- a/cli/dcoscli/data/help/help.txt +++ b/cli/dcoscli/data/help/help.txt @@ -1,11 +1,23 @@ -Display command line usage information +Description: + Display help information about DCOS. Usage: dcos help dcos help --info - dcos help + dcos help + +Commands: + help + Print help information about a subcommand. Options: - --help Show this screen - --info Show a short description of this subcommand - --version Show version + --help + Print usage. + --info + Print a short description of this subcommand. + --version + Print version information. + +Positional Arguments: + + The subcommand name. diff --git a/cli/dcoscli/data/help/marathon.txt b/cli/dcoscli/data/help/marathon.txt index 52de7b7..8d3b707 100644 --- a/cli/dcoscli/data/help/marathon.txt +++ b/cli/dcoscli/data/help/marathon.txt @@ -1,4 +1,5 @@ -Deploy and manage applications on the DCOS +Description: + Deploy and manage applications to DCOS. Usage: dcos marathon --config-schema @@ -18,91 +19,120 @@ Usage: dcos marathon deployment rollback dcos marathon deployment stop dcos marathon deployment watch [--max-count=] - [--interval=] - dcos marathon task list [--json ] - dcos marathon task show + [--interval=] dcos marathon group add [] dcos marathon group list [--json] dcos marathon group scale [--force] dcos marathon group show [--group-version=] dcos marathon group remove [--force] dcos marathon group update [--force] [...] + dcos marathon task list [--json ] + dcos marathon task show + +Commands: + about + Print info.json for DCOS Marathon. + app add + Add an application. + app list + List the installed applications. + app remove + Remove an application. + app restart + Restart an application. + app show + Show the `marathon.json` for an application. + app start + Start an application. + app stop + Stop an application. + app kill + Kill a running application instance. + app update + Update an application. + app version list + List the version history of an application. + deployment list + Print a list of currently deployed applications. + deployment rollback + Remove a deployed application. + deployment stop + Cancel the in-progress deployment of an application. + deployment watch + Monitor deployments. + group add + Create a new group. + group list + Print the list of groups. + group scale + Scale a group. + group show + Print a detailed list of groups. + group remove + Remove a group. + group update + Update a group. + task list + List all tasks. + task show + List a specific task. Options: - -h, --help Show this screen - - --info Show a short description of this - subcommand - - --json Print json-formatted tasks - - --version Show version - - --force This flag disable checks in Marathon - during update operations - - --app-version= This flag specifies the application - version to use for the command. The - application version () can be - specified as an absolute value or as - relative value. Absolute version values - must be in ISO8601 date format. Relative - values must be specified as a negative - integer and they represent the version - from the currently deployed application - definition - - --group-version= This flag specifies the group version to - use for the command. The group version - () can be specified as an - absolute value or as relative value. - Absolute version values must be in ISO8601 - date format. Relative values must be - specified as a negative integer and they - represent the version from the currently - deployed group definition - - --config-schema Show the configuration schema for the - Marathon subcommand - - --max-count= Maximum number of entries to try to fetch - and return - - --interval= Number of seconds to wait between actions - - --scale Scale the app down after performing the - the operation. - - --host= The host name to isolate your command to - + --app-version= + The version of the application to use. It can be specified as an + absolute or relative value. Absolute values must be in ISO8601 date + format. Relative values must be specified as a negative integer and they + represent the version from the currently deployed application definition. + --config-schema + Show the configuration schema for the Marathon subcommand. + --force + Disable checks in Marathon during updates. + --group-version= + The group version to use for the command. It can be specified as an + absolute or relative value. Absolute values must be in ISO8601 date + format. Relative values must be specified as a negative integer and they + represent the version from the currently deployed group definition. + -h, --help + Print usage. + --host= + The hostname that is running app. + --info + Print a short description of this subcommand. + --interval= + Number of seconds to wait between actions. + --json + Print JSON-formatted list of tasks. + --max-count= + Maximum number of entries to fetch and return. + --scale + Scale the app down after performing the the operation. + --version + Print version information. Positional Arguments: - The application id - - Path to a file or HTTP(S) URL containing - the app's JSON definition. If omitted, - the definition is read from stdin. For a - detailed description see - (https://mesosphere.github.io/ - marathon/docs/rest-api.html#post-/v2/apps). - - The deployment id - - The group id - - Path to a file or HTTP(S) URL containing - the group's JSON definition. If omitted, - the definition is read from stdin. For a - detailed description see - (https://mesosphere.github.io/ - marathon/docs/rest-api.html#post-/v2/groups). - - The number of instances to start - - Must be of the format =. E.g. - cpus=2.0. If omitted, properties are read from - stdin. - - The task id - - The factor to scale an application group by + + The application ID. + + Path to a file or HTTP(S) URL that contains the app's JSON definition. + If omitted, the definition is read from stdin. For a detailed + description see + https://mesosphere.github.io/marathon/docs/rest-api.html#post-v2-apps. + + The deployment ID. + + The group ID. + + Path to a file or HTTP(S) URL that contains the group's JSON definition. + If omitted, the definition is read from stdin. For a detailed + description see + https://mesosphere.github.io/marathon/docs/rest-api.html#post-v2-groups. + + The number of instances. + + List of space-separated config.json properties to update. The list must + be formatted as =. For example, `cpus=2.0 mem=308`. If + omitted, properties are read from stdin. + + The task ID. + + The factor to scale an application group by. diff --git a/cli/dcoscli/data/help/node.txt b/cli/dcoscli/data/help/node.txt index 4b10cd7..875b553 100644 --- a/cli/dcoscli/data/help/node.txt +++ b/cli/dcoscli/data/help/node.txt @@ -1,4 +1,5 @@ -Manage DCOS nodes +Description: + Administer and manage DCOS cluster nodes. Usage: dcos node --info @@ -10,22 +11,49 @@ Usage: [--master-proxy] (--leader | --master | --mesos-id= | --slave=) +Commands: + log + Prints the Mesos logs for the leading master node, agent nodes, or both. + ssh + Establish an SSH connection to the master or agent nodes of your DCOS + cluster. + +Commands: + log + Prints the Mesos logs for the leading master node, agent nodes, or both. + ssh + Establish an SSH connection to the master or agent nodes of your DCOS + cluster. + Options: - -h, --help Show this screen - --info Show a short description of this subcommand - --json Print json-formatted nodes - --follow Print data as the file grows - --lines=N Print the last N lines [default: 10] - --leader Access the leading master - --master Deprecated. Please use --leader. - --master-proxy Proxy the SSH connection through a master node. This can be useful when - accessing DCOS from a separate network. For example, in the default AWS - configuration, the private slaves are unreachable from the public - internet. You can access them using this option, which will first hop - from the publicly available master. - --slave= Deprecated. Please use --mesos-id. - --mesos-id= Access the node with the provided Mesos ID - --option SSHOPT=VAL SSH option (see `man ssh_config`) - --config-file= Path to SSH config file - --user= SSH user [default: core] - --version Show version + --config-file= + Path to SSH configuration file. + --follow + Dynamically update the log. + -h, --help + Show this screen. + --info + Show a short description of this subcommand. + --json + Print JSON-formatted list of nodes. + --leader + The leading master. + --lines=N + Print the last N lines, where 10 is the default. + --master + Deprecated. Please use --leader. + --master-proxy + Proxy the SSH connection through a master node. This can be useful when + accessing DCOS from a separate network. For example, in the default AWS + configuration, the private slaves are unreachable from the public + internet. You can access them using this option, which will first hop + from the publicly available master. + --option SSHOPT=VAL + The SSH options. For information, enter `man ssh_config` in your + terminal. + --slave= + Agent node with the provided ID. + --user= + The SSH user, where the default user [default: core]. + --version + Print version information. diff --git a/cli/dcoscli/data/help/package.txt b/cli/dcoscli/data/help/package.txt index 0bee0fd..79a175d 100644 --- a/cli/dcoscli/data/help/package.txt +++ b/cli/dcoscli/data/help/package.txt @@ -1,4 +1,5 @@ -Install and manage DCOS packages +Description: + Install and manage DCOS software packages. Usage: dcos package --config-schema @@ -23,61 +24,71 @@ Usage: dcos package update +Commands: + describe + Get specific details for packages. + install + Install a package. + list + Print a list of the installed DCOS packages. + search + Search the package repository. + repo add + Add a package repository to DCOS. + repo remove + Remove a package repository from DCOS. + repo list + Print the package repository sources. Possible sources include a local + file, HTTPS, and Git. + uninstall + Uninstall a package. + update + This command has been deprecated. Repositories are dynamically updated + as they are added by `dcos package repo add`. + Options: --all - Apply the operation to all matching packages - + All packages. --app - Apply the operation only to the package's Marathon application - + Application only. --app-id= - The application id - + The application ID. --cli - Apply the operation only to the package's CLI command - + Command line only. --config - Print the package's config.json, which contains the configurable - properties for marathon.json and command.json - - -h, --help - Show this screen - + Print the the configurable properties for the `marathon.json` and + `command.json` files. --index= - Index into the list. The first element in the list has an index of zero - + The numerical position in the package repository list. Package + repositories are searched in descending order. By default the Universe + repository first in the list. + -h, --help + Print usage. --info - Show a short description of this subcommand - + Print a short description of this subcommand. --options= - Path to a JSON file containing package installation options - + Path to a JSON file that contains customized package installation options. --package-version= - Package version to install - + The package version to install. --package-versions - Print all versions for this package - + Print all versions for this package. --render - Render the package's marathon.json or command.json template with the + Collate the marathon.json or command.json package templates with the values from config.json and --options. If not provided, print the raw templates. - --version - Show version - + Print version information. --yes - Assume "yes" is the answer to all prompts and run non-interactively + Turn off interactive mode and assume "yes" is the answer to all prompts. Positional Arguments: - Name of the DCOS package - + Name of the DCOS package in the package repository. - Pattern to use for searching for package - + Pattern to use for searching the package repository. You can use + complete or partial values. - Name for repository - + Name of the package repository. For example, `Universe`. - URL of repository of DCOS packages. E.g. https://universe.mesosphere.com/repo + URL of the package repository. For example, + https://universe.mesosphere.com/repo. diff --git a/cli/dcoscli/data/help/service.txt b/cli/dcoscli/data/help/service.txt index 0b11118..b3b1536 100644 --- a/cli/dcoscli/data/help/service.txt +++ b/cli/dcoscli/data/help/service.txt @@ -1,4 +1,5 @@ -Manage DCOS services +Description: + Manage DCOS services. Usage: dcos service --info @@ -7,36 +8,41 @@ Usage: [] dcos service shutdown +Commands: + log + Print the service logs. + + shutdown + Shutdown a service. + Options: - -h, --help Show this screen - - --completed Show completed services in addition to active - ones. Completed services are those that have - been disconnected from master, and have reached - their failover timeout, or have been explicitly - shutdown via the /shutdown endpoint. - - --inactive Show inactive services in addition to active - ones. Inactive services are those that have - been disconnected from master, but haven't yet - reached their failover timeout. - - --info Show a short description of this subcommand - - --follow Print data as the file grows - - --json Print json-formatted services - - --lines=N Print the last N lines [default: 10] - - --ssh-config-file= Path to SSH config file. Used to access - marathon logs. - - --version Show version + --completed + Show the completed and active services. Completed services have either + been disconnected from master and reached their failover timeout, or + have been explicitly shutdown via the /shutdown endpoint. + -h, --help + Print usage. + --follow + Print data as the log file grows. + --inactive + Show the inactive and active services. Inactive services have been + disconnected from master, but haven't yet reached their failover timeout. + --info + Print a short description of this subcommand. + --json + Print JSON-formatted list of DCOS services. + --lines=N + Print the last N lines, where 10 is the default. + --ssh-config-file= + The path to the SSH config file. This is used to access the Marathon + logs. + --version + Print version information. Positional Arguments: - Output this file. [default: stdout] - - The DCOS Service name. - - The DCOS Service ID + + The service log filename for the Mesos sandbox. The default is stdout. + + The DCOS Service name. + + The DCOS Service ID. diff --git a/cli/dcoscli/data/help/task.txt b/cli/dcoscli/data/help/task.txt index 7ea659f..318be1b 100644 --- a/cli/dcoscli/data/help/task.txt +++ b/cli/dcoscli/data/help/task.txt @@ -1,4 +1,5 @@ -Manage DCOS tasks +Description: + Manage DCOS tasks. Usage: dcos task --info @@ -6,18 +7,35 @@ Usage: dcos task log [--completed --follow --lines=N] [] dcos task ls [--long] [] +Command: + log + Print the task log. By default, the 10 most recent task logs from stdout + are printed. + ls + Print the list of files in the Mesos task sandbox. + Options: - -h, --help Show this screen - --info Show a short description of this subcommand - --completed Include completed tasks as well - --follow Print data as the file grows - --json Print json-formatted tasks - --lines=N Print the last N lines [default: 10] - --long Use a long listing format - --version Show version + --completed + Print completed and in-progress tasks. + -h, --help + Print usage. + --info + Print a short description of this subcommand. + --follow + Dynamically update the log. + --json + Print JSON-formatted list of tasks. + --lines=N + Print the last N lines. The default is 10 lines. + --long + Print full Mesos sandbox file attributes. + --version + Print version information. Positional Arguments: - Print this file. [default: stdout] - List this directory. [default: '.'] - Only match tasks whose ID matches . may be - a substring of the ID, or a unix glob pattern. + + Specify the sandbox file to print. The default is stdout. + + The Mesos sandbox directory path. The default is '.'. + + A full task ID, a partial task ID, or a regular expression. diff --git a/cli/dcoscli/help/main.py b/cli/dcoscli/help/main.py index 12597e3..4c4573b 100644 --- a/cli/dcoscli/help/main.py +++ b/cli/dcoscli/help/main.py @@ -6,6 +6,7 @@ import pkg_resources from concurrent.futures import ThreadPoolExecutor from dcos import cmds, emitting, options, subcommand, util from dcos.errors import DCOSException +from dcoscli.common import command_info from dcoscli.main import decorate_docopt_usage emitter = emitting.FlatEmitter() @@ -54,7 +55,7 @@ def _cmds(): cmds.Command( hierarchy=['help'], - arg_keys=[''], + arg_keys=[''], function=_help), ] @@ -65,7 +66,7 @@ def _info(): :rtype: int """ - emitter.publish(_doc().split('\n')[0]) + emitter.publish(command_info(_doc())) return 0 diff --git a/cli/dcoscli/marathon/main.py b/cli/dcoscli/marathon/main.py index c02a43a..5bc3fee 100644 --- a/cli/dcoscli/marathon/main.py +++ b/cli/dcoscli/marathon/main.py @@ -9,6 +9,7 @@ import pkg_resources from dcos import cmds, emitting, http, jsonitem, marathon, options, util from dcos.errors import DCOSException from dcoscli import tables +from dcoscli.common import command_info from dcoscli.main import decorate_docopt_usage logger = util.get_logger(__name__) @@ -200,7 +201,7 @@ def _info(): :rtype: int """ - emitter.publish(_doc().split('\n')[0]) + emitter.publish(command_info(_doc())) return 0 diff --git a/cli/dcoscli/node/main.py b/cli/dcoscli/node/main.py index 70a48e2..805db77 100644 --- a/cli/dcoscli/node/main.py +++ b/cli/dcoscli/node/main.py @@ -7,6 +7,7 @@ import pkg_resources from dcos import cmds, emitting, errors, mesos, util from dcos.errors import DCOSException, DefaultError from dcoscli import log, tables +from dcoscli.common import command_info from dcoscli.main import decorate_docopt_usage logger = util.get_logger(__name__) @@ -87,7 +88,7 @@ def _info(): :rtype: int """ - emitter.publish(_doc().split('\n')[0]) + emitter.publish(command_info(_doc())) return 0 @@ -132,6 +133,8 @@ def _log(follow, lines, leader, slave): if not (leader or slave): raise DCOSException('You must choose one of --leader or --mesos-id.') + if lines is None: + lines = 10 lines = util.parse_int(lines) mesos_files = _mesos_files(leader, slave) diff --git a/cli/dcoscli/package/main.py b/cli/dcoscli/package/main.py index 96e02c9..a3fddf7 100644 --- a/cli/dcoscli/package/main.py +++ b/cli/dcoscli/package/main.py @@ -13,6 +13,7 @@ from dcos import (cmds, cosmospackage, emitting, errors, http, options, package, subcommand, util) from dcos.errors import DCOSException from dcoscli import tables +from dcoscli.common import command_info from dcoscli.main import decorate_docopt_usage from six import iteritems @@ -139,7 +140,7 @@ def _info(): :rtype: int """ - emitter.publish(_doc().split('\n')[0]) + emitter.publish(command_info(_doc())) return 0 diff --git a/cli/dcoscli/service/main.py b/cli/dcoscli/service/main.py index 7e5d354..74935f4 100644 --- a/cli/dcoscli/service/main.py +++ b/cli/dcoscli/service/main.py @@ -6,6 +6,7 @@ import pkg_resources from dcos import cmds, emitting, marathon, mesos, util from dcos.errors import DCOSException, DefaultError from dcoscli import log, tables +from dcoscli.common import command_info from dcoscli.main import decorate_docopt_usage logger = util.get_logger(__name__) @@ -78,7 +79,7 @@ def _info(): :rtype: int """ - emitter.publish(_doc().split('\n')[0]) + emitter.publish(command_info(_doc())) return 0 @@ -141,6 +142,8 @@ def _log(follow, lines, ssh_config_file, service, file_): :rtype: int """ + if lines is None: + lines = 10 lines = util.parse_int(lines) if service == 'marathon': diff --git a/cli/dcoscli/task/main.py b/cli/dcoscli/task/main.py index 518b9b1..bc95fb4 100644 --- a/cli/dcoscli/task/main.py +++ b/cli/dcoscli/task/main.py @@ -6,6 +6,7 @@ import pkg_resources from dcos import cmds, emitting, mesos, util from dcos.errors import DCOSException, DCOSHTTPException, DefaultError from dcoscli import log, tables +from dcoscli.common import command_info from dcoscli.main import decorate_docopt_usage logger = util.get_logger(__name__) @@ -77,7 +78,7 @@ def _info(): :rtype: int """ - emitter.publish(_doc().split('\n')[0]) + emitter.publish(command_info(_doc())) return 0 @@ -136,6 +137,8 @@ def _log(follow, completed, lines, task, file_): if file_ is None: file_ = 'stdout' + if lines is None: + lines = 10 lines = util.parse_int(lines) # get tasks diff --git a/cli/tests/data/help/config.txt b/cli/tests/data/help/config.txt index 63b5ee7..73d097f 100644 --- a/cli/tests/data/help/config.txt +++ b/cli/tests/data/help/config.txt @@ -1,4 +1,5 @@ -Get and set DCOS CLI configuration properties +Description: + Manage the DCOS configuration file. Usage: dcos config --info @@ -7,11 +8,26 @@ Usage: dcos config unset dcos config validate +Commands: + set + Add or set a DCOS configuration property. + show + Print the DCOS configuration file contents. + unset + Remove a property from the configuration file. + validate + Validate changes to the configuration file. + Options: - -h, --help Show this screen - --info Show a short description of this subcommand - --version Show version + -h, --help + Print usage. + --info + Print a short description of this subcommand. + --version + Print version information. Positional Arguments: - The name of the property - The value of the property + + The name of the property. + + The value of the property. diff --git a/cli/tests/data/help/dcos.txt b/cli/tests/data/help/dcos.txt index ea70dd7..20869c3 100644 --- a/cli/tests/data/help/dcos.txt +++ b/cli/tests/data/help/dcos.txt @@ -1,39 +1,39 @@ -Command line utility for the Mesosphere Datacenter Operating -System (DCOS) - -'dcos help' lists all available subcommands. See 'dcos --help' -to read about a specific subcommand. +Description: + The Mesosphere Datacenter Operating System (DCOS) spans all of the machines in +your datacenter or cloud and treats them as a single, shared set of resources. Usage: dcos [options] [] [...] Options: - --help Show this screen - --version Show version - --log-level= If set then print supplementary messages to - stderr at or above this level. The severity - levels in the order of severity are: debug, - info, warning, error, and critical. E.g. - Setting the option to warning will print - warning, error and critical messages to stderr. - Note: that this does not affect the output sent - to stdout by the command. - --debug If set then enable further debug messages which - are sent to stdout. + --debug + Enable debug mode. + --help + Print usage. + --log-level= + Set the logging level. This setting does not affect the output sent to + stdout. The severity levels are: + The severity level: + * debug Prints all messages. + * info Prints informational, warning, error, and critical messages. + * warning Prints warning, error, and critical messages. + * error Prints error and critical messages. + * critical Prints only critical messages to stderr. + --version + Print version information Environment Variables: - DCOS_LOG_LEVEL If set then it specifies that message should be - printed to stderr at or above this level. See - the --log-level option for details. - - DCOS_CONFIG This environment variable points to the - location of the DCOS configuration file. - [default: ~/.dcos/dcos.toml] - - DCOS_DEBUG If set then enable further debug messages which - are sent to stdout. - - DCOS_SSL_VERIFY If set, specifies whether to verify SSL certs - for HTTPS, or the path to the certificate(s). - Can also be configured by setting - `core.ssl_config` in the config. + DCOS_CONFIG + Set the path to the DCOS configuration file. By default, this variable + is set to ~/.dcos/dcos.toml. + DCOS_DEBUG + Indicates whether to print additional debug messages to stdout. By + default this is set to false. + DCOS_LOG_LEVEL + Prints log messages to stderr at or above the level indicated. This is + equivalent to the --log-level command-line option. + DCOS_SSL_VERIFY + Indicates whether to verify SSL certificates for HTTPS (true) or set the + path to the SSL certificates (false). By default, this is variable is + set to true. This is equivalent to setting the `core.ssl_config` option + in the DCOS configuration file. diff --git a/cli/tests/data/help/default.txt b/cli/tests/data/help/default.txt new file mode 100644 index 0000000..a255916 --- /dev/null +++ b/cli/tests/data/help/default.txt @@ -0,0 +1,16 @@ +Command line utility for the Mesosphere Datacenter Operating +System (DCOS). The Mesosphere DCOS is a distributed operating +system built around Apache Mesos. This utility provides tools +for easy management of a DCOS installation. + +Available DCOS commands: + + config Manage the DCOS configuration file + help Display help information about DCOS + marathon Deploy and manage applications to DCOS + node Administer and manage DCOS cluster nodes + package Install and manage DCOS software packages + service Manage DCOS services + task Manage DCOS tasks + +Get detailed command description with 'dcos --help'. diff --git a/cli/tests/data/help/help.txt b/cli/tests/data/help/help.txt index 8f3b8b9..fa49396 100644 --- a/cli/tests/data/help/help.txt +++ b/cli/tests/data/help/help.txt @@ -1,11 +1,23 @@ -Display command line usage information +Description: + Display help information about DCOS. Usage: dcos help dcos help --info - dcos help + dcos help + +Commands: + help + Print help information about a subcommand. Options: - --help Show this screen - --info Show a short description of this subcommand - --version Show version + --help + Print usage. + --info + Print a short description of this subcommand. + --version + Print version information. + +Positional Arguments: + + The subcommand name. diff --git a/cli/tests/data/help/marathon.txt b/cli/tests/data/help/marathon.txt index 52de7b7..8d3b707 100644 --- a/cli/tests/data/help/marathon.txt +++ b/cli/tests/data/help/marathon.txt @@ -1,4 +1,5 @@ -Deploy and manage applications on the DCOS +Description: + Deploy and manage applications to DCOS. Usage: dcos marathon --config-schema @@ -18,91 +19,120 @@ Usage: dcos marathon deployment rollback dcos marathon deployment stop dcos marathon deployment watch [--max-count=] - [--interval=] - dcos marathon task list [--json ] - dcos marathon task show + [--interval=] dcos marathon group add [] dcos marathon group list [--json] dcos marathon group scale [--force] dcos marathon group show [--group-version=] dcos marathon group remove [--force] dcos marathon group update [--force] [...] + dcos marathon task list [--json ] + dcos marathon task show + +Commands: + about + Print info.json for DCOS Marathon. + app add + Add an application. + app list + List the installed applications. + app remove + Remove an application. + app restart + Restart an application. + app show + Show the `marathon.json` for an application. + app start + Start an application. + app stop + Stop an application. + app kill + Kill a running application instance. + app update + Update an application. + app version list + List the version history of an application. + deployment list + Print a list of currently deployed applications. + deployment rollback + Remove a deployed application. + deployment stop + Cancel the in-progress deployment of an application. + deployment watch + Monitor deployments. + group add + Create a new group. + group list + Print the list of groups. + group scale + Scale a group. + group show + Print a detailed list of groups. + group remove + Remove a group. + group update + Update a group. + task list + List all tasks. + task show + List a specific task. Options: - -h, --help Show this screen - - --info Show a short description of this - subcommand - - --json Print json-formatted tasks - - --version Show version - - --force This flag disable checks in Marathon - during update operations - - --app-version= This flag specifies the application - version to use for the command. The - application version () can be - specified as an absolute value or as - relative value. Absolute version values - must be in ISO8601 date format. Relative - values must be specified as a negative - integer and they represent the version - from the currently deployed application - definition - - --group-version= This flag specifies the group version to - use for the command. The group version - () can be specified as an - absolute value or as relative value. - Absolute version values must be in ISO8601 - date format. Relative values must be - specified as a negative integer and they - represent the version from the currently - deployed group definition - - --config-schema Show the configuration schema for the - Marathon subcommand - - --max-count= Maximum number of entries to try to fetch - and return - - --interval= Number of seconds to wait between actions - - --scale Scale the app down after performing the - the operation. - - --host= The host name to isolate your command to - + --app-version= + The version of the application to use. It can be specified as an + absolute or relative value. Absolute values must be in ISO8601 date + format. Relative values must be specified as a negative integer and they + represent the version from the currently deployed application definition. + --config-schema + Show the configuration schema for the Marathon subcommand. + --force + Disable checks in Marathon during updates. + --group-version= + The group version to use for the command. It can be specified as an + absolute or relative value. Absolute values must be in ISO8601 date + format. Relative values must be specified as a negative integer and they + represent the version from the currently deployed group definition. + -h, --help + Print usage. + --host= + The hostname that is running app. + --info + Print a short description of this subcommand. + --interval= + Number of seconds to wait between actions. + --json + Print JSON-formatted list of tasks. + --max-count= + Maximum number of entries to fetch and return. + --scale + Scale the app down after performing the the operation. + --version + Print version information. Positional Arguments: - The application id - - Path to a file or HTTP(S) URL containing - the app's JSON definition. If omitted, - the definition is read from stdin. For a - detailed description see - (https://mesosphere.github.io/ - marathon/docs/rest-api.html#post-/v2/apps). - - The deployment id - - The group id - - Path to a file or HTTP(S) URL containing - the group's JSON definition. If omitted, - the definition is read from stdin. For a - detailed description see - (https://mesosphere.github.io/ - marathon/docs/rest-api.html#post-/v2/groups). - - The number of instances to start - - Must be of the format =. E.g. - cpus=2.0. If omitted, properties are read from - stdin. - - The task id - - The factor to scale an application group by + + The application ID. + + Path to a file or HTTP(S) URL that contains the app's JSON definition. + If omitted, the definition is read from stdin. For a detailed + description see + https://mesosphere.github.io/marathon/docs/rest-api.html#post-v2-apps. + + The deployment ID. + + The group ID. + + Path to a file or HTTP(S) URL that contains the group's JSON definition. + If omitted, the definition is read from stdin. For a detailed + description see + https://mesosphere.github.io/marathon/docs/rest-api.html#post-v2-groups. + + The number of instances. + + List of space-separated config.json properties to update. The list must + be formatted as =. For example, `cpus=2.0 mem=308`. If + omitted, properties are read from stdin. + + The task ID. + + The factor to scale an application group by. diff --git a/cli/tests/data/help/node.txt b/cli/tests/data/help/node.txt index 4b10cd7..875b553 100644 --- a/cli/tests/data/help/node.txt +++ b/cli/tests/data/help/node.txt @@ -1,4 +1,5 @@ -Manage DCOS nodes +Description: + Administer and manage DCOS cluster nodes. Usage: dcos node --info @@ -10,22 +11,49 @@ Usage: [--master-proxy] (--leader | --master | --mesos-id= | --slave=) +Commands: + log + Prints the Mesos logs for the leading master node, agent nodes, or both. + ssh + Establish an SSH connection to the master or agent nodes of your DCOS + cluster. + +Commands: + log + Prints the Mesos logs for the leading master node, agent nodes, or both. + ssh + Establish an SSH connection to the master or agent nodes of your DCOS + cluster. + Options: - -h, --help Show this screen - --info Show a short description of this subcommand - --json Print json-formatted nodes - --follow Print data as the file grows - --lines=N Print the last N lines [default: 10] - --leader Access the leading master - --master Deprecated. Please use --leader. - --master-proxy Proxy the SSH connection through a master node. This can be useful when - accessing DCOS from a separate network. For example, in the default AWS - configuration, the private slaves are unreachable from the public - internet. You can access them using this option, which will first hop - from the publicly available master. - --slave= Deprecated. Please use --mesos-id. - --mesos-id= Access the node with the provided Mesos ID - --option SSHOPT=VAL SSH option (see `man ssh_config`) - --config-file= Path to SSH config file - --user= SSH user [default: core] - --version Show version + --config-file= + Path to SSH configuration file. + --follow + Dynamically update the log. + -h, --help + Show this screen. + --info + Show a short description of this subcommand. + --json + Print JSON-formatted list of nodes. + --leader + The leading master. + --lines=N + Print the last N lines, where 10 is the default. + --master + Deprecated. Please use --leader. + --master-proxy + Proxy the SSH connection through a master node. This can be useful when + accessing DCOS from a separate network. For example, in the default AWS + configuration, the private slaves are unreachable from the public + internet. You can access them using this option, which will first hop + from the publicly available master. + --option SSHOPT=VAL + The SSH options. For information, enter `man ssh_config` in your + terminal. + --slave= + Agent node with the provided ID. + --user= + The SSH user, where the default user [default: core]. + --version + Print version information. diff --git a/cli/tests/data/help/package.txt b/cli/tests/data/help/package.txt index 0bee0fd..79a175d 100644 --- a/cli/tests/data/help/package.txt +++ b/cli/tests/data/help/package.txt @@ -1,4 +1,5 @@ -Install and manage DCOS packages +Description: + Install and manage DCOS software packages. Usage: dcos package --config-schema @@ -23,61 +24,71 @@ Usage: dcos package update +Commands: + describe + Get specific details for packages. + install + Install a package. + list + Print a list of the installed DCOS packages. + search + Search the package repository. + repo add + Add a package repository to DCOS. + repo remove + Remove a package repository from DCOS. + repo list + Print the package repository sources. Possible sources include a local + file, HTTPS, and Git. + uninstall + Uninstall a package. + update + This command has been deprecated. Repositories are dynamically updated + as they are added by `dcos package repo add`. + Options: --all - Apply the operation to all matching packages - + All packages. --app - Apply the operation only to the package's Marathon application - + Application only. --app-id= - The application id - + The application ID. --cli - Apply the operation only to the package's CLI command - + Command line only. --config - Print the package's config.json, which contains the configurable - properties for marathon.json and command.json - - -h, --help - Show this screen - + Print the the configurable properties for the `marathon.json` and + `command.json` files. --index= - Index into the list. The first element in the list has an index of zero - + The numerical position in the package repository list. Package + repositories are searched in descending order. By default the Universe + repository first in the list. + -h, --help + Print usage. --info - Show a short description of this subcommand - + Print a short description of this subcommand. --options= - Path to a JSON file containing package installation options - + Path to a JSON file that contains customized package installation options. --package-version= - Package version to install - + The package version to install. --package-versions - Print all versions for this package - + Print all versions for this package. --render - Render the package's marathon.json or command.json template with the + Collate the marathon.json or command.json package templates with the values from config.json and --options. If not provided, print the raw templates. - --version - Show version - + Print version information. --yes - Assume "yes" is the answer to all prompts and run non-interactively + Turn off interactive mode and assume "yes" is the answer to all prompts. Positional Arguments: - Name of the DCOS package - + Name of the DCOS package in the package repository. - Pattern to use for searching for package - + Pattern to use for searching the package repository. You can use + complete or partial values. - Name for repository - + Name of the package repository. For example, `Universe`. - URL of repository of DCOS packages. E.g. https://universe.mesosphere.com/repo + URL of the package repository. For example, + https://universe.mesosphere.com/repo. diff --git a/cli/tests/data/help/service.txt b/cli/tests/data/help/service.txt index 0b11118..b3b1536 100644 --- a/cli/tests/data/help/service.txt +++ b/cli/tests/data/help/service.txt @@ -1,4 +1,5 @@ -Manage DCOS services +Description: + Manage DCOS services. Usage: dcos service --info @@ -7,36 +8,41 @@ Usage: [] dcos service shutdown +Commands: + log + Print the service logs. + + shutdown + Shutdown a service. + Options: - -h, --help Show this screen - - --completed Show completed services in addition to active - ones. Completed services are those that have - been disconnected from master, and have reached - their failover timeout, or have been explicitly - shutdown via the /shutdown endpoint. - - --inactive Show inactive services in addition to active - ones. Inactive services are those that have - been disconnected from master, but haven't yet - reached their failover timeout. - - --info Show a short description of this subcommand - - --follow Print data as the file grows - - --json Print json-formatted services - - --lines=N Print the last N lines [default: 10] - - --ssh-config-file= Path to SSH config file. Used to access - marathon logs. - - --version Show version + --completed + Show the completed and active services. Completed services have either + been disconnected from master and reached their failover timeout, or + have been explicitly shutdown via the /shutdown endpoint. + -h, --help + Print usage. + --follow + Print data as the log file grows. + --inactive + Show the inactive and active services. Inactive services have been + disconnected from master, but haven't yet reached their failover timeout. + --info + Print a short description of this subcommand. + --json + Print JSON-formatted list of DCOS services. + --lines=N + Print the last N lines, where 10 is the default. + --ssh-config-file= + The path to the SSH config file. This is used to access the Marathon + logs. + --version + Print version information. Positional Arguments: - Output this file. [default: stdout] - - The DCOS Service name. - - The DCOS Service ID + + The service log filename for the Mesos sandbox. The default is stdout. + + The DCOS Service name. + + The DCOS Service ID. diff --git a/cli/tests/data/help/task.txt b/cli/tests/data/help/task.txt index 7ea659f..318be1b 100644 --- a/cli/tests/data/help/task.txt +++ b/cli/tests/data/help/task.txt @@ -1,4 +1,5 @@ -Manage DCOS tasks +Description: + Manage DCOS tasks. Usage: dcos task --info @@ -6,18 +7,35 @@ Usage: dcos task log [--completed --follow --lines=N] [] dcos task ls [--long] [] +Command: + log + Print the task log. By default, the 10 most recent task logs from stdout + are printed. + ls + Print the list of files in the Mesos task sandbox. + Options: - -h, --help Show this screen - --info Show a short description of this subcommand - --completed Include completed tasks as well - --follow Print data as the file grows - --json Print json-formatted tasks - --lines=N Print the last N lines [default: 10] - --long Use a long listing format - --version Show version + --completed + Print completed and in-progress tasks. + -h, --help + Print usage. + --info + Print a short description of this subcommand. + --follow + Dynamically update the log. + --json + Print JSON-formatted list of tasks. + --lines=N + Print the last N lines. The default is 10 lines. + --long + Print full Mesos sandbox file attributes. + --version + Print version information. Positional Arguments: - Print this file. [default: stdout] - List this directory. [default: '.'] - Only match tasks whose ID matches . may be - a substring of the ID, or a unix glob pattern. + + Specify the sandbox file to print. The default is stdout. + + The Mesos sandbox directory path. The default is '.'. + + A full task ID, a partial task ID, or a regular expression. diff --git a/cli/tests/integrations/test_config.py b/cli/tests/integrations/test_config.py index 403e88d..0bfd81d 100644 --- a/cli/tests/integrations/test_config.py +++ b/cli/tests/integrations/test_config.py @@ -40,7 +40,7 @@ def test_help(): def test_info(): - stdout = b'Get and set DCOS CLI configuration properties\n' + stdout = b'Manage the DCOS configuration file\n' assert_command(['dcos', 'config', '--info'], stdout=stdout) diff --git a/cli/tests/integrations/test_dcos.py b/cli/tests/integrations/test_dcos.py index 7497281..8f981b8 100644 --- a/cli/tests/integrations/test_dcos.py +++ b/cli/tests/integrations/test_dcos.py @@ -2,28 +2,9 @@ from .common import assert_command, exec_command def test_default(): - returncode, stdout, stderr = exec_command(['dcos']) - - assert returncode == 0 - assert stdout == """\ -Command line utility for the Mesosphere Datacenter Operating -System (DCOS). The Mesosphere DCOS is a distributed operating -system built around Apache Mesos. This utility provides tools -for easy management of a DCOS installation. - -Available DCOS commands: - -\tconfig \tGet and set DCOS CLI configuration properties -\thelp \tDisplay command line usage information -\tmarathon \tDeploy and manage applications on the DCOS -\tnode \tManage DCOS nodes -\tpackage \tInstall and manage DCOS packages -\tservice \tManage DCOS services -\ttask \tManage DCOS tasks - -Get detailed command description with 'dcos --help'. -""".encode('utf-8') - assert stderr == b'' + with open('tests/data/help/default.txt') as content: + assert_command(['dcos'], + stdout=content.read().encode('utf-8')) def test_help(): @@ -42,7 +23,7 @@ def test_log_level_flag(): ['dcos', '--log-level=info', 'config', '--info']) assert returncode == 0 - assert stdout == b"Get and set DCOS CLI configuration properties\n" + assert stdout == b"Manage the DCOS configuration file\n" def test_capital_log_level_flag(): @@ -50,7 +31,7 @@ def test_capital_log_level_flag(): ['dcos', '--log-level=INFO', 'config', '--info']) assert returncode == 0 - assert stdout == b"Get and set DCOS CLI configuration properties\n" + assert stdout == b"Manage the DCOS configuration file\n" def test_invalid_log_level_flag(): diff --git a/cli/tests/integrations/test_help.py b/cli/tests/integrations/test_help.py index de0422c..10584b9 100644 --- a/cli/tests/integrations/test_help.py +++ b/cli/tests/integrations/test_help.py @@ -9,7 +9,7 @@ def test_help(): def test_info(): assert_command(['dcos', 'help', '--info'], - stdout=b'Display command line usage information\n') + stdout=b'Display help information about DCOS\n') def test_version(): @@ -26,11 +26,11 @@ for easy management of a DCOS installation. Available DCOS commands: -\tconfig \tGet and set DCOS CLI configuration properties -\thelp \tDisplay command line usage information -\tmarathon \tDeploy and manage applications on the DCOS -\tnode \tManage DCOS nodes -\tpackage \tInstall and manage DCOS packages +\tconfig \tManage the DCOS configuration file +\thelp \tDisplay help information about DCOS +\tmarathon \tDeploy and manage applications to DCOS +\tnode \tAdminister and manage DCOS cluster nodes +\tpackage \tInstall and manage DCOS software packages \tservice \tManage DCOS services \ttask \tManage DCOS tasks diff --git a/cli/tests/integrations/test_marathon.py b/cli/tests/integrations/test_marathon.py index ad70add..efc346c 100644 --- a/cli/tests/integrations/test_marathon.py +++ b/cli/tests/integrations/test_marathon.py @@ -29,7 +29,7 @@ def test_version(): def test_info(): assert_command(['dcos', 'marathon', '--info'], - stdout=b'Deploy and manage applications on the DCOS\n') + stdout=b'Deploy and manage applications to DCOS\n') def test_about(): diff --git a/cli/tests/integrations/test_node.py b/cli/tests/integrations/test_node.py index fadea9d..262ba27 100644 --- a/cli/tests/integrations/test_node.py +++ b/cli/tests/integrations/test_node.py @@ -18,7 +18,7 @@ def test_help(): def test_info(): - stdout = b"Manage DCOS nodes\n" + stdout = b"Administer and manage DCOS cluster nodes\n" assert_command(['dcos', 'node', '--info'], stdout=stdout) diff --git a/cli/tests/integrations/test_package.py b/cli/tests/integrations/test_package.py index 2646219..7fa435b 100644 --- a/cli/tests/integrations/test_package.py +++ b/cli/tests/integrations/test_package.py @@ -43,8 +43,9 @@ def test_package(): def test_info(): + info = b"Install and manage DCOS software packages\n" assert_command(['dcos', 'package', '--info'], - stdout=b'Install and manage DCOS packages\n') + stdout=info) def test_version(): diff --git a/dcos/data/config-schema/core.json b/dcos/data/config-schema/core.json index 4677e77..99095ff 100644 --- a/dcos/data/config-schema/core.json +++ b/dcos/data/config-schema/core.json @@ -3,13 +3,13 @@ "additionalProperties": false, "properties": { "dcos_url": { - "description": "The URL to the location of the DCOS", + "description": "The the public master IP of your DCOS installation", "format": "uri", "title": "DCOS URL", "type": "string" }, "dcos_acs_token": { - "description": "token generated by authenticating to DCOS with acs", + "description": "This is the token generated by authenticating to DCOS with ACS", "title": "DCOS ACS token", "type": "string" }, @@ -19,14 +19,14 @@ "type": "string" }, "mesos_master_url": { - "description": "Mesos Master URL. Must be of the format: \"http://host:port\"", + "description": "Mesos master URL. Must be set in format: \"http://host:port\"", "format": "uri", "title": "Mesos Master URL", "type": "string" }, "refresh_token": { "description": "Your OAuth refresh token", - "title": "Your OAuth refresh token", + "title": "The OAuth refresh token", "type": "string" }, "reporting": { @@ -51,7 +51,7 @@ "type": "string", "default": "false", "title": "SSL Verification", - "description": "Whether or not to verify SSL certs for HTTPS or path to cert(s)" + "description": "Whether to verify SSL certs for HTTPS or path to certs" } }, "type": "object"