From dd0501ee1fc9e33d6c06f6f8e5be306727270b67 Mon Sep 17 00:00:00 2001 From: William Albertus Dembo Date: Thu, 3 Oct 2019 11:20:45 +0700 Subject: [PATCH] Add cli feature list on readme --- README.md | 3 + docs/features.md | 295 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 298 insertions(+) create mode 100644 docs/features.md diff --git a/README.md b/README.md index fcb7fc89..f5ef7c6f 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,9 @@ Bundle repetitive task as a automation and turn it into `procs` to make it easie Before we goes deep down into explanation about proctor, you may want to read about [Proctor Glossary](docs/glossary.md) +## Feature list +Section for full features list of proctor CLI is separated [here](./docs/features.md) + ## Installation This section provide installation for unix environment. diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 00000000..ef17d3dd --- /dev/null +++ b/docs/features.md @@ -0,0 +1,295 @@ +# Proctor CLI Feature + +- [proctor config \](#proctor-config) +- [proctor config show](#proctor-config-show) +- [proctor describe \](#proctor-describe-proc) +- [proctor execute \ \](#proctor-execute-proc-params) +- [proctor help](#proctor-help) +- [proctor list](#proctor-list) +- [proctor logs \](#proctor-logs-execution-id) +- [proctor schedule \ \](#proctor-schedule-proc-params) +- [proctor schedule describe \](#proctor-schedule-describe-schedule-id) +- [proctor schedule list](#proctor-schedule-list) +- [proctor schedule remove <\schedule-id\>](#proctor-schedule-remove-schedule-id) +- [proctor status \](#proctor-status-execution-id) +- [proctor template \](#proctor-template-proc) + +## proctor config +Set configuration to run proctor. +Proctor client keep the configuration on ~/.proctor/proctor.yaml + +### Params +| Key | Description | Required | +|:------------- |:------------------------------------- |:--------:| +| PROCTOR_HOST | Host address of proctor service | yes | +| EMAIL_ID | Email account for auth process | no | +| ACCESS_TOKEN | Account access token for auth process | no | + +### Example +```shell script +foo@bar:~$ proctor config PROCTOR_HOST=proctor.com EMAIL_ID=mr.proctor@gmail.com ACCESS_TOKEN=MR_PROCTOR +Proctor client configured successfully +``` + +## proctor config show +Use this command to show current configuration + +### Example +```shell script +foo@bar:~$ proctor config show +PROCTOR_HOST: proctor.com +EMAIL_ID: mr.proctor@gmail.com +ACCESS_TOKEN: MR_PROCTOR +``` + +## proctor describe \ +Use this command to learn more about \ + +### Params +| Key | Description | Required | +|:------------- |:------------------------------------- |:--------:| +| \ | Name of proc | yes | + +### Example +```shell script +foo@bar:~$ proctor describe echo-worker +Description I will echo your name +Contributors Mr.Proctor +Organization Proctor +Authorized Groups [] + +Args +name name to echo +``` + +## proctor execute \ \ +Execute proc on server with specified params + +### Params +| Key | Description | Required | +|:------------- |:------------------------------------- |:--------:| +| \ | Name of proc | yes | + +Other params depend on proc requirements + +### Flags +| Flag | Description | +|:------------- |:------------------------------------- | +| --filename -f | Insert proc parameters from yaml file | + +### Example +```shell script +foo@bar:~$ proctor execute echo-worker name=Mr.Proctor +Executing Proc echo-worker +With Variables +name Mr.Proctor + +Execution Created +ID 1826735143124102 +Name proctor-1289c792631 + +Streaming logs +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor + +Execution completed. +``` + +## proctor help +Show proctor client help text + +### Example +```shell script +foo@bar~:$ proctor help +A command-line interface to run procs + +Usage: + proctor [command] + +Available Commands: + config Configure proctor client + describe Help on executing a proc + execute Execute a proc with given arguments + help Help about any command + list List procs available for execution + logs Get logs of an execution context + schedule Create scheduled procs + status Get status of an execution context + template Get input template of a procs + version Print version of Proctor command-line tool + +Flags: + -h, --help help for proctor + +Use "proctor [command] --help" for more information about a command. +``` + +## proctor list +Show list of available procs + +### Example +```shell script +foo@bar~:$ proctor list +List of Procs: + +echo-worker echo-worker + +For detailed information of any proc, run: +proctor describe +``` + +## proctor logs \ +Stream logs from executed proc, this process will continue until execution complete + +### Params +| Key | Description | Required | +|:---------------- |:----------------------------------------- |:--------:| +| \ | Execution ID generated by execute command | yes | + +Other params depend on proc requirements + +### Example +```shell script +foo@bar:~$ proctor logs 1826735143124102 +Getting logs +ID 1826735143124102 + +Streaming logs +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor +Mr.Proctor + + +Execution completed. +``` + +## proctor schedule \ \ +Run a proc on scheduled basis specified with cron format + +### Params +| Key | Description | Required | +|:---------------- |:----------------------------------------- |:--------:| +| \ | Proc name to scheduled | yes | + +### Flags +| Flag | Description | Required | +|:------------- |:------------------------------------------------------- |:--------:| +| --cron -c | Schedule in cron format ([link](https://crontab.guru/)) | yes | +| --group -g | Group Name | yes | +| --notify -n | Email to notify schedule progress | yes | +| --tags -T | Schedule tags for management purpose | yes | + + +### Example +```shell script +foo@bar:~$ proctor schedule echo-worker name=Mr.Proctor -g proctor -c '0 2 * * *' -T 'proctor' -n mr.proctor@gmail.com +Creating Scheduled Job echo-worker +With Variables +name Mr.Proctor +Scheduled Job UUID : 269349349056612582 +``` + +## proctor schedule describe \ +Get more information about scheduled proc + +### Params +| Key | Description | Required | +|:---------------- |:----------------------------------------- |:--------:| +| \ | Schedule id to learn | yes | + +### Example +```shell script +foo@bar:~$ proctor schedule describe 269349349056612582 +ID 269349349056612582 +PROC NAME echo-worker +GROUP NAME proctor +TAGS proctor +Cron 0 0 2 * * * +Notifier mr.proctor@gmail.com + +Args +name Mr.Proctor +``` + +## proctor schedule list +Get list of scheduled procs + +### Example +```shell script +foo@bar:~$ proctor schedule list +ID PROC NAME GROUP NAME TAGS +269349349056612582 diagnose-vm system-test test,proctor +``` + +## proctor schedule remove <\schedule-id\> +Remove scheduled procs + +### Params +| Key | Description | Required | +|:---------------- |:----------------------------------------- |:--------:| +| \ | Schedule id to remove | yes | + +### Example +```shell script +foo@bar:~$ proctor schedule remove 269349349056612582 +Sucessfully removed the scheduled job ID: 269349349056612582 +``` + +## proctor status \ +Get status of executed proc + +### Params +| Key | Description | Required | +|:---------------- |:----------------------------------------- |:--------:| +| \ | Execution id to get | yes | + +### Example +```shell script +foo@bar:~$ proctor status 1826735143124102 +Getting status +ID 1826735143124102 +Job Name echo-worker +Status FINISHED +Updated At 2019-10-03 04:00:58.083798 +0000 +0000 +Execution completed. +``` + + +## proctor template \ \ +Render yaml template to use with [execute](#proctor-execute-proc-params) command + +### Params +| Key | Description | Required | +|:---------------- |:----------------------------------------- |:--------:| +| \ | Proc name to render | yes | +| \ | Yaml to keep the result | yes | + +### Example +```shell script +foo@bar:~$ proctor template echo-worker echo-worker.yaml + +Args +name [Mandatory] name to echo + +To echo-worker, run: +proctor execute echo-worker -f echo-worker.yaml + +foo@bar:~$ cat echo-worker.yaml +# [Mandatory] name to echo +name: +```