From 211f24476a8920df2b4074db11de76fecf3079da Mon Sep 17 00:00:00 2001 From: David Erwin Date: Tue, 11 Jul 2017 14:39:26 -0400 Subject: [PATCH 1/3] Create cli docs --- docs/_data/sidebars/talk_sidebar.yml | 3 + docs/architecture-cli.md | 133 +++++++++++++++++++++++++++ docs/architecture.md | 2 +- 3 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 docs/architecture-cli.md diff --git a/docs/_data/sidebars/talk_sidebar.yml b/docs/_data/sidebars/talk_sidebar.yml index ed307b88e..62660783c 100644 --- a/docs/_data/sidebars/talk_sidebar.yml +++ b/docs/_data/sidebars/talk_sidebar.yml @@ -46,6 +46,9 @@ entries: - title: Tags url: /architecture-tags.html output: web + - title: cli + url: /architecture-cli.html + output: web - title: Plugins diff --git a/docs/architecture-cli.md b/docs/architecture-cli.md new file mode 100644 index 000000000..d4f22ae76 --- /dev/null +++ b/docs/architecture-cli.md @@ -0,0 +1,133 @@ +--- +title: The Talk cli +keywords: architecture +sidebar: talk_sidebar +permalink: architecture-cli.html +summary: +--- + +Talk ships with a cli tool that allows access to a wide variety of functionality. + +It is designed to provide a convenient way for engineers to perform key tasks without the need to muck about in the UI. It also opens the door for scripts to perform operations programmatically. + +Note: the cli tool requires [the Talk environment to be configured](configuration.html) either via env vars or by using a `.cli` file via `bin/cli -c .env [command] ....` + +## Using the cli + +In a terminal, try: + +``` +/path/to/talk/bin cli [options] [commands] [arguments] +``` + +Commonly, you'll be in the `talk/` folder, in which case you can: + +``` +bin cli [options] [commands] [arguments] +``` + +If you're a heavy cli user, consider adding the `bin` folder to your path so you can run `cli` from anywhere! + +## What can I do with the cli? + +The Talk cli ships with 'unix style' help. To access the docs, simply run the cli with insufficient arguments. + +Let's say I wanted to figure out how to change a user's password. I'd start be seeing what the cli has for me. + +``` +talk :) ]$ bin/cli + + Usage: cli [options] [command] + + + Commands: + + serve serve the application + settings interact with the application settings + assets interact with assets + setup setup the application + jobs work with the job queues + token work with the access tokens + users work with the application auth + migration provides utilities for migrating the database + plugins provides utilities for interacting with the plugin system + help [cmd] display help for [cmd] + + Options: + + -h, --help output usage information + -V, --version output the version number + -c, --config [path] Specify the configuration file to load + --pid [path] Specify a path to output the current PID to +``` + +Most commands contain sub-commands. Running with cli with such a command generates the docs for the sub-commands and options therein. + +Change user password is likely to be in the `users` command group. + +``` +talk :) ]$ bin/cli users + + Usage: cli-users [options] [command] + + + Commands: + + create [options] create a new user + delete delete a user + passwd change a password for a user + update [options] update a user + list list all the users in the database + merge merge srcUser into the dstUser + addrole adds a role to a given user + removerole removes a role from a given user + ban ban a given user + uban unban a given user + disable disable a given user from logging in + enable enable a given user from logging in + + Options: + + -h, --help output usage information + -V, --version output the version number + -c, --config [path] Specify the configuration file to load + --pid [path] Specify a path to output the current PID to +``` + +I now see that I can change a password like so: + +``` +bin/cli users passwd [userID] +``` + +You can also read these help prompts by [exploring the source code](https://github.com/coralproject/talk/blob/master/bin/cli). + +### Usage Notes + +If you haven't used a cli enabled system before, think of it like this: generally, you'd make a rest call, rpc, etc... to perform an action. The cli's api is designed in the same way, just for the audience of command line wielding engineers and scripts. + +The best way to understand what the cli does is to explore the help commands. Uses of cli are also scattered through this documentation in context of their topics. + +For some real world uses of the cli, see the scripts in the [package.json file](https://github.com/coralproject/talk/blob/d688f70c19d8dee48371784009fd07322dae4eb5/package.json#L8). + +## What's really going on when I run the cli? + +The cli tool is a standalone application. Running it starts up the internals of a talk process, executes the given command, then shuts it down. No server functionality is enabled by cli commands unless specifically noted. + +The cli tool _does not require a talk server to be running._ This means that you can execute commands, for example, during and installation process before starting the server. The also means that you can execute commands using varying configurations (via the `-c [.env file]` flag). + +### Accessing existing Talk installs with the cli + +You may use the cli tool to 'remotely' control existing talk installs. + +This is accomplished by running the cli tool on any box using the mongo/redis/etc... credentials for the environment that you would like to act on. For example, if you want something to happen periodically on your production Talk install, you could set up a utility box with a cron job that triggers the cli with the same db/cache credentials. If you want to do something quick on a staging server, you could run the cli locally with staging credentials. + +The cli tool will connect directly with the install's db and redis instance(s) so ensure that your box can reach those servers on the appropriate ports. + +Please secure your environments and credentials or the cli tool becomes a convenient way for someone to own your system. + +## Extending the cli + +The Talk cli is based on the excellent [commander](https://github.com/tj/commander.js/) library. + +At the time of writing, there are no plugin hooks for the cli tool. If you would like to change this, whether by writing code yourself or recommending a need, please [write and issue](https://github.com/coralproject/talk/blob/053b687959d45bcd682a1a2a4b604ebfab7441bb/CONTRIBUTING.md#writing-code). diff --git a/docs/architecture.md b/docs/architecture.md index 36a8d5c1d..180e172ac 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -31,7 +31,7 @@ Our goal is to continually extend our plugin infrastructure making the Core as p ### cli -Talk ships with a cli tool that exposes functionality to the command line. We seek to provide cli functionality for all features that could need to be accomplished programmatically or prior to the server's startup. +Talk ships with [a cli tool](architecture-cli.html) that exposes functionality to the command line. We seek to provide cli functionality for all features that could need to be accomplished programmatically or prior to the server's startup. ## Thinking about Plugins, the Plugin API and Core? From eafcadd6a113e3fcc5a59eef9da29896c6c77a73 Mon Sep 17 00:00:00 2001 From: David Erwin Date: Tue, 11 Jul 2017 14:43:59 -0400 Subject: [PATCH 2/3] Warn users more --- docs/architecture-cli.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/architecture-cli.md b/docs/architecture-cli.md index d4f22ae76..37095d27d 100644 --- a/docs/architecture-cli.md +++ b/docs/architecture-cli.md @@ -124,6 +124,8 @@ This is accomplished by running the cli tool on any box using the mongo/redis/et The cli tool will connect directly with the install's db and redis instance(s) so ensure that your box can reach those servers on the appropriate ports. +Also, _please ensure your cli and the server(s) in an environment are using the same version of Talk._ + Please secure your environments and credentials or the cli tool becomes a convenient way for someone to own your system. ## Extending the cli From a9c6014634901ae5074237f3ae09ff3cc3809821 Mon Sep 17 00:00:00 2001 From: David Erwin Date: Tue, 11 Jul 2017 15:05:52 -0400 Subject: [PATCH 3/3] Add more info --- docs/architecture-cli.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/architecture-cli.md b/docs/architecture-cli.md index 37095d27d..3079890d4 100644 --- a/docs/architecture-cli.md +++ b/docs/architecture-cli.md @@ -23,10 +23,12 @@ In a terminal, try: Commonly, you'll be in the `talk/` folder, in which case you can: ``` -bin cli [options] [commands] [arguments] +bin/cli [options] [commands] [arguments] ``` -If you're a heavy cli user, consider adding the `bin` folder to your path so you can run `cli` from anywhere! +If you're a heavy cli user, consider adding the `bin` folder to your PATH so you can run `cli` from anywhere! + +If you are using [our Docker environment](install-docker.html), the bin folder will already be in the PATH. ## What can I do with the cli? @@ -34,8 +36,10 @@ The Talk cli ships with 'unix style' help. To access the docs, simply run the cl Let's say I wanted to figure out how to change a user's password. I'd start be seeing what the cli has for me. +(Note: the following output may change, please reference at the `--help` output for your version as you use the cli.) + ``` -talk :) ]$ bin/cli +talk :) ]$ bin/cli --help Usage: cli [options] [command] @@ -124,7 +128,7 @@ This is accomplished by running the cli tool on any box using the mongo/redis/et The cli tool will connect directly with the install's db and redis instance(s) so ensure that your box can reach those servers on the appropriate ports. -Also, _please ensure your cli and the server(s) in an environment are using the same version of Talk._ +Also, _please ensure your cli and the server(s) in an environment are using the same version of Talk._ Please secure your environments and credentials or the cli tool becomes a convenient way for someone to own your system.