docs: introduce new Clever Tools documentation

bin/clever.js

@@ -348,7 +348,7 @@ function run () {
       parser: Parsers.commaSeparated,
     }),
     showAllActivity: cliparse.flag('show-all', { description: 'Show all activity' }),
-    showAll: cliparse.flag('show-all', { description: 'Show all available dependencies' }),
+    showAll: cliparse.flag('show-all', { description: 'Show all available add-ons and applications' }),
     loginToken: cliparse.option('token', {
       metavar: 'token',
       description: 'Directly give an existing token',

docs/README.md

@@ -0,0 +1,90 @@
+# How to use Clever Tools
+
+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 an 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
+[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.
+
+- [How to install Clever Tools](/docs/setup-systems.md)
+- [Create a Clever Cloud account](https://console.clever-cloud.com)
+
+You'll find below the first commands to know to connect Clever Tools to your account, get its informations and manage some options. Others are developed in dedicated pages:
+
+- [Applications: configuration](/docs/applications-config.md)
+- [Applications: management](/docs/applications-management.md)
+- [Applications: deployment and lifecycle](/docs/applications-deployment-lifecycle.md)
+- [Add-ons: management and backups](/docs/addons-backups.md)
+- [Services: depedencies](/docs/services-depedencies.md)
+- [Services: logs drains](/docs/services-logs-drains.md)
+- [Services: notifications and webhooks](/docs/services-notifications-webhooks.md)
+
+## basic commands
+
+To show Clever tools available commands, use:
+
+```
+clever
+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)
+```
+
+## diag | version
+
+To check the current version or get informations about your setup, use:
+
+```
+clever version
+clever diag
+```
+
+> [!NOTE]
+> Such informations are nice to provide in your issues report or when you contact Clever Cloud technical support team.
+
+## login | logout
+
+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.
+
+If you already know them, you can use:
+
+```
+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:
+
+```
+clever logout
+```
+
+## profile
+
+To get informations about the current logged in user (ID, name, email, 2FA activation), use:
+
+```
+clever profile
+```
+
+## 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 an use exactly the same way as the famous tool, 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

@@ -0,0 +1,74 @@
+# Clever Cloud Add-ons: management and backups
+
+Add-ons on Clever Cloud are databases, storage services, tools or third party services you can enable through ` clever addon provider`. For each of the folowing commands, you can target a specific user/organisation:
+
+```
+[--org, -o, --owner]                Organisation ID (or name, if unambiguous)
+```
+
+## providers
+
+To use add-ons, you need to identify the corresponding provider. To get informations about them (plans, regions, versions), use:
+
+```
+clever addon providers
+clever addon providers show PROVIDER_NAME
+```
+
+## create | rename | delete
+
+To create an add-on, select a provider and choose a name:
+
+```
+clever addon create PROVIDER ADDON_NAME
+```
+
+You can set `plan`, `region`, `version`, `option` and directly `link` an add-on to an application through these parameters:
+
+```
+[--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)
+[--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
+```
+
+To rename an add-on, use:
+
+```
+clever addon rename ADDON_ID_OR_NAME ADDON_NEW_NAME
+```
+
+To delete an add-on, use:
+
+```
+clever addon delete [--yes, -y] ADDON_ID_OR_NAME
+```
+
+## env
+
+Each add-on comes with environement variables. To get them, use:
+
+```
+clever addon env [--format, -F] FORMAT ADDON_ID
+```
+
+> [!NOTE] 
+> Available formats are: `human` (default), `json` and `shell`
+
+## database backups
+
+Databases are backup every day, with last 7 days of backups available to download. To get these files, use:
+
+```
+clever database backups download [--output, --out] OUTPUT_FILE DATABASE_ID BACKUP_ID
+```
+
+This command is still under development and will evolve over time. To get informations about backups and download them, you can use our API and `clever curl`. For example:
+
+```
+clever curl -X GET https://api.clever-cloud.com/v2/backups/<USER_ORG_ID>/<DATABASE_ID>
+```
+
+This will list available backups for the database, with creation and delete time. The anwser will also contains a direct HTTPS `download_url`.

docs/applications-config.md

@@ -0,0 +1,128 @@
+# 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`.
+
+## config
+
+Each application have options you can get/set: `name`, `description`, `zero-downtime`, `sticky-sessions`, `cancel-on-push`, `force-https`.
+
+```
+clever config get parameter
+clever config set parameter value
+```
+
+To update multiple configuration parameters at a time, use:
+
+```
+clever config update FLAGS
+```
+
+Available parameters are :
+
+```
+[--name]                        Set name
+[--description]                 Set description
+[--enable-zero-downtime]        Enable zero-downtime (default: false)
+[--disable-zero-downtime]       Disable zero-downtime (default: false)
+[--enable-sticky-sessions]      Enable sticky-sessions (default: false)
+[--disable-sticky-sessions]     Disable sticky-sessions (default: false)
+[--enable-cancel-on-push]       Enable cancel-on-push (default: false)
+[--disable-cancel-on-push]      Disable cancel-on-push (default: false)
+[--enable-force-https]          Enable force-https (default: false)
+[--disable-force-https]         Disable force-https (default: false)
+```
+
+## env
+
+Environment variables of Clever Cloud applications can easily be modified:
+
+```
+clever env set VARIABLE VALUE
+clever env rm VARIABLE
+```
+
+You can import local environment variables (comma separated) or from a file through `stdin`. If it's a JSON file, each object should be composed of a `name` and a `value`.
+
+```
+clever env import-vars VAR_NAME1,VAR_NAME2
+clever env import < .env
+cat .env.json | clever env import --json
+```
+
+To show or export environment variables of an application, use:
+
+```
+clever env
+clever env > .env
+```
+
+You can also export environment variable in a sourceable format (`export ENV_NAME="VALUE";`):
+
+```
+clever env --add-export
+```
+
+## domain
+
+By default, a Clever Cloud application gets an `app_id.cleverapps.io`. To see it, use:
+
+```
+clever domain
+```
+
+To add/remove domains through these commands, use:
+
+```
+add                        Add a domain name to a Clever Cloud application
+favourite                  Manage Clever Cloud application favourite domain name
+rm                         Remove a domain name from a Clever Cloud application
+```
+
+> [!TIP]
+> You can 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
+
+To (un)set the favourite domain, use:
+
+```
+clever domain favourite set FQDN
+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 provides 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
+[--min-flavor] MINFLAVOR           The minimum scale for your application
+[--max-flavor] MAXFLAVOR           The maximum scale for your application
+[--instances] INSTANCES            The number of parallels instances
+[--min-instances] MININSTANCES     The minimum number of parallels instances
+[--max-instances] MAXINSTANCES     The maximum number of parallels instances
+[--build-flavor] BUILDFLAVOR       The size of the build instance, or `disabled`
+```
+
+> [!NOTE]
+> Available instances flavors are: `pico`, `nano`, `XS`, `S`, `M`, `L`, `XL`, `2XL`, `3XL`
+>
+> Due to its low memory (256 MiB) `pico` is not always available. When selected, a dedicated `S` instance is used for build by default.
+
+## tcp-redirs
+
+A Clever Cloud application activate TCP redirections in `default` or `cleverapps` namespace:
+
+```
+clever tcp-redirs add --namespace NAMESPACE
+clever tcp-redirs remove --namespace NAMESPACE PORT
+```
+
+To list enabled TCP redirection, use:
+
+```
+clever tcp-redirs
+```
+
+- [Learn more about TCP redirections](https://developers.clever-cloud.com/doc/administrate/tcp-redirections/)