docs: v3.8 update

README.md

@@ -27,7 +27,7 @@ We also distribute binaries and packages for multiple systems and tools:
   * [Chocolatey](docs/setup-systems.md#chocolatey)
   * [Binary (.zip)](docs/setup-systems.md#binary-zip)
 * [Docker](docs/setup-systems.md#docker)
-* [Nix](docs/setup-systems.md#nix-package-manager)
+* [Nix package manager](docs/setup-systems.md#nix-package-manager)
 
 ## Enabling autocompletion
 

docs/README.md

@@ -2,7 +2,7 @@
 
 Clever Tools is the command line interface (CLI) of Clever Cloud. You can use it to create and manage multiple services of the platform as applications, databases or storage add-ons. It also provides easy authenticated access to Clever Cloud public APIv2 and APIv4 through the [`clever curl` command](#curl).
 
-It's an [easy to setup](/docs/setup-systems.md) multiplatform and open source tool, based on Node.js. You can contribute to it through
+It's an [easy to set up](/docs/setup-systems.md) multiplatform and open source tool, based on Node.js. You can contribute to it through
 [issue](https://github.com/CleverCloud/clever-tools/issues) or [pull requests](https://github.com/CleverCloud/clever-tools/pulls). You're free
 to ask for new features, enhancements or help us to provide them to our community.
 
@@ -31,19 +31,24 @@ clever help
 For each of them, you can add these parameters:
 
 ```
-[--help, -?]               Display help about this program (default: false)
-[--version, -V]            Display the version of this program (default: false)
-[--verbose, -v]            Verbose output (default: false)
-[--no-update-notifier]     Don't notify available updates for clever-tools (default: false)
+[--help, -?]            Display help about this program (default: false)
+[--version, -V]         Display the version of this program (default: false)
+[--color]               Choose whether to print colors or not. You can also use --no-color (default: true)
+[--update-notifier]     Choose whether to use update notifier or not. You can also use --no-update-notifier (default: true)
+[--verbose, -v]         Verbose output (default: false)
 ```
 
+> [!TIP]
+> For commands returning a list of items, you can use `--format json` or `-F json` to get a JSON output.
+
 ## diag | version
 
 To check the current version or get information about your setup, use:
 
 ```
 clever version
 clever diag
+clever diag --format json
 ```
 
 > [!NOTE]
@@ -57,7 +62,7 @@ To connect to your Clever Cloud account, use:
 clever login
 ```
 
-It will open your default browser and start an Open Authorization ([OAuth](https://en.wikipedia.org/wiki/OAuth)) process get a `token` and `secret` pair added in your account if it succeeds. You can manage it from the [Console](https://console.clever-cloud.com/users/me/tokens). Clever Tools will automatically store these `token` and `secret` values in a hidden `clever-tools.json` config file in the current local user home folder.
+It will open your default browser and start an Open Authorization ([OAuth](https://en.wikipedia.org/wiki/OAuth)) process to get a `token` and `secret` pair added in your account if it succeeds. You can manage it from the [Console](https://console.clever-cloud.com/users/me/tokens). Clever Tools will automatically store these `token` and `secret` values in a hidden `clever-tools.json` config file in the current local user home folder.
 
 If you already know them, you can use:
 
@@ -68,23 +73,24 @@ clever login --secret SECRET --token TOKEN
 > [!TIP]
 > If environment variables `CC_SECRET` and `CC_TOKEN` are set, Clever Tools will use them, `login` is not needed.
 
-To logout, delete this file or use:
+To log out, delete this file or use:
 
 ```
 clever logout
 ```
 
 ## profile
 
-To get information about the current logged-in user (ID, name, email, 2FA activation), use:
+To get information about the current logged-in user (ID, name, email, 2FA activation, etc.), use:
 
 ```
 clever profile
+clever profile -F json
 ```
 
 ## curl
 
-To use our public API, you need to be authentified on many endpoints. If you're logged in through Clever Tools, there is a simple way to make any request you want: `clever curl`. It's `curl`, you can use exactly the same way as the famous tool, but in an authenticated context for Clever Cloud API.
+To use our public API, you need to be authenticated for most endpoints. If you're logged in through Clever Tools, there is a simple way to make any request you want: `clever curl`. It's `curl`, but in an authenticated context for Clever Cloud API.
 
 - [Clever Cloud public APIv2 documentation](https://developers.clever-cloud.com/api/v2/)
 - [Clever Cloud public APIv4 documentation](https://developers.clever-cloud.com/api/v4/)

docs/addons-backups.md

@@ -28,13 +28,16 @@ You can set `plan`, `region`, `version`, `option` and directly `link` an add-on
 ```
 [--link, -l] ALIAS                  Link the created add-on to the app with the specified alias
 [--yes, -y]                         Skip confirmation even if the add-on is not free (default: false)
-[--plan, -p] PLAN                   Add-on plan, depends on the provider (default: dev)
+[--plan, -p] PLAN                   Add-on plan, depends on the provider
 [--region, -r] REGION               Region to provision the add-on in, depends on the provider (default: par)
 [--addon-version] ADDON-VERSION     The version to use for the add-on
 [--option] OPTION                   Option to enable for the add-on. Multiple --option argument can be passed to enable multiple options
 [--format, -F] FORMAT               Output format (human, json) (default: human)
 ```
 
+> [!NOTE]
+> If no plan is set, we use the cheapest by default
+
 To rename an add-on, use:
 
 ```

docs/applications-config.md

@@ -1,6 +1,6 @@
 # Clever Cloud Applications: configuration
 
-A Clever Cloud application can easily be configured once created, through following commands. Each can target a specfic application in the current folder, adding `[--alias, -a] ALIAS`.
+A Clever Cloud application can easily be configured once created, through following commands. All can target a specific application, adding `--app APP_ID_OR_NAME` or a local alias (`--alias`, `-a`).
 
 ## config
 
@@ -64,7 +64,7 @@ clever env --add-export
 
 ## domain
 
-By default, a Clever Cloud application gets an `app_id.cleverapps.io`. To see it, use:
+By default, a Clever Cloud application gets `app_id.cleverapps.io` as fully qualified domain name ([FQDN](https://fr.wikipedia.org/wiki/Fully_qualified_domain_name)). To see it, use:
 
 ```
 clever domain
@@ -79,7 +79,7 @@ rm                         Remove a domain name from a Clever Cloud application
 ```
 
 > [!TIP]
-> You can set the same domain with multiple apps thanks to [prefix routing](https://developers.clever-cloud.com/doc/administrate/domain-names/#prefix-routing), regex are also supported. For example, you can add `mydomain.com/app1` domain to an application and `mydomain.com/app2` to another
+> You can set the same domain with multiple apps thanks to [prefix routing](https://developers.clever-cloud.com/doc/administrate/domain-names/#prefix-routing). For example, you can add `mydomain.com/app1` domain to an application and `mydomain.com/app2` to another.
 
 To (un)set the favourite domain, use:
 
@@ -90,7 +90,7 @@ clever domain favourite unset FQDN
 
 ## scale and dedicated build
 
-You can easily change the number of instances and `flavor` for an application. It can also have a different `flavor` used for build phase, to get it done faster. We also provide horizontal and vertical scaling: you can set a minimal/maximal `flavor` and number of instance, then we autoscale depending on incoming load. To change this, use `clever scale` with the following options:
+You can easily change the number of instances and `flavor` for an application. It can have a different `flavor` used for build phase, to get it done faster. We also provide horizontal and vertical scaling: you can set a minimal/maximal `flavor` and number of instance, then we autoscale depending on incoming load. To change this, use `clever scale` with the following options:
 
 ```
 [--flavor] FLAVOR                  The scale of your application
@@ -120,6 +120,7 @@ To list enabled TCP redirection, use:
 
 ```
 clever tcp-redirs
+clever tcp-redirs --format json
 ```
 
 - [Learn more about TCP redirections](https://developers.clever-cloud.com/doc/administrate/tcp-redirections/)

docs/applications-deployment-lifecycle.md

@@ -1,8 +1,8 @@
 # Clever Cloud Applications: deployment and lifecycle
 
-A Clever Cloud application can easily be deployed and accessed once created, through following commands. Each can target a specific application in the current folder, adding `[--alias, -a] ALIAS`.
+A Clever Cloud application can easily be deployed and accessed once created, through following commands. Most can target a specific application, adding `--app APP_ID_OR_NAME` or a local alias (`--alias`, `-a`).
 
-## deploy | cancel
+## deploy
 
 Once changes are committed in your local git repository, you can deploy it:
 
@@ -13,12 +13,13 @@ clever deploy
 It will `git push` your code on the remote repository of your application on Clever Cloud automatically. You can, of course, use option to `force push` or use specific local branch for example:
 
 ```
-[--branch, -b] BRANCH                             Branch to push (current branch by default) (default: )
-[--tag, -t] TAG                                   Tag to push (none by default) (default: )
-[--quiet, -q]                                     Don't show logs during deployment (default: false)
-[--force, -f]                                     Force deploy even if it's not fast-forwardable (default: false)
-[--follow]                                        Continue to follow logs after deployment has ended (default: false)
-[--same-commit-policy, -p] SAME-COMMIT-POLICY     Which policy to apply when the local commit is the same as the remote one. Available policies are (error, ignore, restart, rebuild) (default: error)
+[--branch, -b] BRANCH                 Branch to push (current branch by default) (default: )
+[--tag, -t] TAG                       Tag to push (none by default) (default: )
+[--quiet, -q]                         Don't show logs during deployment (default: false)
+[--force, -f]                         Force deploy even if it's not fast-forwardable (default: false)
+[--follow]                            Continue to follow logs after deployment has ended (default: false)
+[--same-commit-policy, -p] POLICY     What to do when local and remote commit are identical (error, ignore, restart, rebuild) (default: error)
+[--exit-on, -e] STEP                  Step at which the logs streaming is ended, steps are: deploy-start, deploy-end, never (default: deploy-end)
 ```
 
 > [!TIP]
@@ -39,6 +40,7 @@ To get application state, options or running/scaling status, use:
 
 ```
 clever status
+clever status --format json
 ```
 
 ## restart
@@ -52,10 +54,20 @@ clever restart
 By default, it will use its build cache when available. But you can override it or use other available options:
 
 ```
-[--commit] COMMIT ID       Restart the application with a specific commit id
+[--commit] COMMIT ID       Restart the application with a specific commit ID
 [--without-cache]          Restart the application without using cache (default: false)
 [--quiet, -q]              Don't show logs during deployment (default: false)
 [--follow]                 Continue to follow logs after deployment has ended (default: false)
+[--exit-on, -e] STEP       Step at which the logs streaming is ended, steps are: deploy-start, deploy-end, never (default: deploy-end)
+```
+
+## stop | cancel-deploy
+
+To stop an application or cancel any ongoing deployment, use:
+
+```
+clever stop
+clever cancel-deploy
 ```
 
 ## ssh
@@ -66,6 +78,12 @@ A Clever Cloud application is a running virtual machine you can ssh to, as a use
 clever ssh [--identity-file, -i] IDENTITY-FILE
 ```
 
+To ssh a specific application, use:
+
+```
+clever ssh --app APP_ID_OR_NAME
+```
+
 ## logs
 
 When you deploy an application on Clever Cloud, we collect its logs, hosted in our internal Pulsar stack, all included. To listen to the stream, use:
@@ -93,16 +111,33 @@ When you deploy an application on Clever Cloud, we collect its access logs, host
 clever accesslogs
 ```
 
+> [!TIP]
+>  This now uses our v4 API, it's available as Alpha feature for now.
+
 You can also get access logs from a specific timeline or add-on through options, in multiple formats:
 
 ```
-[--format, -F] FORMAT          Output format (human, json, simple, extended, clf) (default: human)
-[--before, --until] BEFORE          Fetch logs before this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h)
-[--after, --since] AFTER       Fetch logs after this date (ISO8601)
-[--follow, -f]                 Display access logs continuously (ignores before/until, after/since) (default: false)
-[--addon] ADDON_ID             Add-on ID
+[--before, --until] BEFORE     Fetch logs before this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h)
+[--after, --since] AFTER       Fetch logs after this date/time (ISO8601)
+[--format, -F] FORMAT          Output format (human, json, json-stream) (default: human)
+```
+
+You can for example get access logs in JSON format for the last hour with:
+
+```
+clever accesslogs --format json --since 1h
 ```
 
+or use `jq` to filter the output:
+
+```
+clever accesslogs --app APP_NAME --since 2024-06-21T13:37:42 --until 1d -F json | jq '[.[] | {date, countryCode: .source.countryCode, ip: .source.ip, port: .source.port}]'
+clever accesslogs --app APP_NAME --since 2024-06-21T13:37:42 --until 1d -F json | jq '.[] | [.date, .source.countryCode, .source.ip, .source.port] | @sh'
+```
+
+> [!TIP]
+> `jq` offers multiple table formatting options, like `@csv`, `@tsv`, `@json`, `@html`, `@uri`, `@base64`, etc.
+
 ## activity
 
 To get deployment activity, use:
@@ -116,4 +151,5 @@ By default, it will show you last 10 deployments. You can show all or listen to
 ```
 [--follow, -f]             Track new deployments in activity list (default: false)
 [--show-all]               Show all activity (default: false)
+[--format, -F] FORMAT      Output format (human, json, json-stream)
 ```

docs/applications-management.md

@@ -2,12 +2,16 @@
 
 ## create
 
-You can create a new application on Clever Cloud, linked to your local folder. Only its `type` is required, it should be one of: `docker`, `elixir`, `go`, `gradle`, `haskell`, `jar`,`maven`, `meteor`, `node`, `php`, `play1`, `play2`, `python`, `ruby`, `rust`, `sbt`, `static-apache` or `war`.
+You can create a new application on Clever Cloud, linked to your local folder. Only its `type` is required, it should be one of: `docker`, `elixir`, `go`, `gradle`, `haskell`, `jar`,`maven`, `meteor`, `node`, `php`, `play1`, `play2`, `python`, `ruby`, `rust`, `sbt`, `static-apache` or `war`. Result can be printed in `human` or `json` format.
 
 ```
-clever create -t TYPE [APP-NAME]
+clever create -t TYPE APP_NAME
+clever create -t TYPE --format json
 ```
 
+> [!NOTE]
+> Application name is optional. The current directory name is used if not specified.
+
 You can also use one of the following optional parameters:
 
 #### Tasks
@@ -39,6 +43,7 @@ You can ask to deploy your application in a specific organisation/user account,
 [--org, -o, --owner] ID/NAME
 [--alias, -a] ALIAS
 [--region, -r] ZONE
+[--format, -F] FORMAT
 ```
 
 Default region is our Paris datacenters (`par`), but it can be:
@@ -61,10 +66,10 @@ After the application creation, you can ask for a `json` formatted report instea
 
 ## (un)link and make-default
 
-If an application already exists in your Clever Cloud account, you can link it to any local directory to control it. You can even link several applications to a single folder, each one with a different name and/or alias. This is done through the `.clever.json` file.
+If an application already exists in your Clever Cloud account, you can link it to any local directory to control it easily. You can even link several applications to a single folder, each one with a different name and/or alias. This is done through the `.clever.json` file.
 
 ```
-clever link APP_ID/NAME [--alias, -a] ALIAS [--org, -o, --owner] ID/NAME
+clever link APP_ID_OR_NAME [--alias, -a] ALIAS [--org, -o, --owner] ORG_ID_OR_NAME
 ```
 
 If multiple applications are linked, you can define one as default with it alias:
@@ -94,12 +99,23 @@ If you only need to get aliases or the result in the JSON format:
 [--json, -j]               Show result in JSON format (default: false)
 ```
 
+## list
+
+To list all applications across all organisations you have access to, you can use:
+
+```
+clever applications list -F json
+clever applications list --org ORG_ID_OR_NAME
+```
+
 ## delete
 
 To delete an application and unlink it from the current folder you only need to:
 
 ```
-clever delete [--alias, -a] ALIAS
+clever delete
+clever delete --alias ALIAS
+clever delete --app APP_ID_OR_NAME
 ```
 
 > [!TIP]

docs/services-depedencies.md

@@ -2,10 +2,18 @@
 
 On Clever Cloud, applications can expose configuration to share environment variables with other services within the same account/organization. Add-ons are preconfigured with an exposed configuration. Thus, when they're linked to an application, they automatically share credentials or important variables needed to configure and use them.
 
-Following commands help you with that. Each can target a specific application in the current folder, adding `[--alias, -a] ALIAS`.
+Following commands help you with that. Each can target a specific application, adding `--app APP_ID_OR_NAME` or a local alias (`--alias`, `-a`).
 
 ## published-config
 
+To list exposed configuration, use:
+
+```
+clever published-config
+clever published-config --F json
+clever published-config --format shell
+```
+
 To configure exposed configuration, use:
 
 ```
@@ -24,6 +32,7 @@ To list services dependencies, use:
 
 ```
 clever service
+clever service --format json
 ```
 
 You can filter results through these options.

docs/services-logs-drains.md

@@ -1,21 +1,34 @@
 # Clever Cloud Logs Drains
 
-You can use Clever Tools to control logs drains:
+You can use Clever Tools to control logs drains, through following commands. Each can target a specific add-on with `--addon ADDON_ID ` or application, adding `--app APP_ID_OR_NAME` or a local alias (`--alias`, `-a`):
 
 ```
-clever drain [--alias <alias>]
-clever drain create [--alias <alias>] <DRAIN-TYPE> <DRAIN-URL> [--username <username>] [--password <password>]
-clever drain remove [--alias <alias>] <DRAIN-ID>
+clever drain
+clever drain --format json
+clever drain create <DRAIN-TYPE> <DRAIN-URL>
+clever drain remove <DRAIN-ID>
+clever drain enable <DRAIN-ID>
+clever drain disable <DRAIN-ID>
 ```
 
 Where `DRAIN-TYPE` is one of:
 
-- `TCPSyslog`: for TCP syslog endpoint
-- `UDPSyslog`: for UDP syslog endpoint
-- `HTTP`: for TCP syslog endpoint (note that this endpoint has optional username/password parameters as HTTP Basic Authentication)
-- `ElasticSearch`: for ElasticSearch endpoint (note that this endpoint requires username/password parameters as HTTP Basic Authentication)
 - `DatadogHTTP`: for Datadog endpoint (note that this endpoint needs your Datadog API Key)
+- `ElasticSearch`: for ElasticSearch endpoint (note that this endpoint requires username/password parameters as HTTP Basic Authentication)
+- `HTTP`: for TCP syslog endpoint (note that this endpoint has optional username/password parameters as HTTP Basic Authentication)
 - `NewRelicHTTP`: for NewRelic endpoint (note that this endpoint needs your NewRelic API Key)
+- `TCPSyslog`: for TCP syslog endpoint
+- `UDPSyslog`: for UDP syslog endpoint
+
+Drain creation supports the following options:
+
+```
+[--username, -u] USERNAME             (HTTP drains) basic auth username
+[--password, -p] PASSWORD             (HTTP drains) basic auth password
+[--api-key, -k] API_KEY               (NewRelic drains) API key
+[--index-prefix, -i] INDEX_PREFIX     (ElasticSearch drains) Index prefix (default: logstash-<YYYY-MM-DD>)
+[--sd-params, -s] SD_PARAMS           (TCP and UDP drains) sd-params string (e.g.: `X-OVH-TOKEN=\"REDACTED\"`)
+```
 
 ## ElasticSearch logs drains