From cf563f7e2559c71331dd3184291899d70cfa8835 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 14:56:50 +0200 Subject: [PATCH 01/25] fix(tooling): regenerate the CLI reference at its new location from a release tag --- update-cli-reference.sh | 111 +++++++++++++++++++++++++++++----------- 1 file changed, 80 insertions(+), 31 deletions(-) diff --git a/update-cli-reference.sh b/update-cli-reference.sh index 23899dec7..45f65b677 100755 --- a/update-cli-reference.sh +++ b/update-cli-reference.sh @@ -1,31 +1,80 @@ -#!/bin/bash - -FILE="content/doc/reference/cli.md" -URL="https://raw.githubusercontent.com/CleverCloud/clever-tools/refs/heads/master/skills/clever-tools/references/full-documentation.md" - -front_matter="""--- -type: docs -linkTitle: CLI reference -title: Clever Tools - CLI commands reference -description: Clever Tools commands reference to create and manage Clever Cloud applications, add-ons and services. Ideal to provide to LLMS and AI assisted IDEs. -keywords: -- cli -- clever-tools -- commands -- reference -- applications -- add-ons -aliases: -- /doc/reference/clever-tools/configure -- /doc/reference/clever-tools/manage -- /doc/reference/clever-tools/create -- /doc/reference/clever-tools/lifecycle -- /reference/clever-tools -- /reference/clever-tools/getting_started ---- - - -""" - -echo "${front_matter}" > "${FILE}" -curl -fSL "${URL}" >> "${FILE}" +#!/usr/bin/env bash +# Regenerate the CLI reference page from the documentation of a Clever Tools release +# Usage: ./update-cli-reference.sh [VERSION], defaults to the latest release +set -euo pipefail + +FILE="content/doc/cli-reference.md" +REPO="CleverCloud/clever-tools" + +cd "$(dirname "$0")" + +if [ ! -f "${FILE}" ]; then + echo "${FILE} not found, its front matter is kept from one regeneration to the next" >&2 + exit 1 +fi + +VERSION="${1:-$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" | sed -nE 's/^[[:space:]]*"tag_name":[[:space:]]*"([^"]+)".*/\1/p')}" +if [ -z "${VERSION}" ]; then + echo "Unable to find the latest Clever Tools release, pass a version as argument" >&2 + exit 1 +fi +URL="https://raw.githubusercontent.com/${REPO}/refs/tags/${VERSION}/skills/clever-tools/references/full-documentation.md" + +TMP="$(mktemp)" +trap 'rm -f "${TMP}" "${FILE}.new"' EXIT + +# Download before writing anything, so a failed request leaves the page untouched +curl -fsSL "${URL}" -o "${TMP}" + +{ + # Keep the front matter of the current page, it is maintained here, not upstream + awk 'NR == 1 && $0 != "---" { exit 1 } { print } NR > 1 && $0 == "---" { exit }' "${FILE}" + printf '\n\n\n' + # Normalize the generated Markdown to pass the site's markdownlint rules + perl -e ' + my ($in_code, $has_output, $need_blank, $prev) = (0, 0, 0, ""); + sub emit { + my ($line) = @_; + print "\n" if $need_blank && $has_output; + print "$line\n"; + ($need_blank, $has_output, $prev) = (0, 1, $line); + } + # Apply a substitution outside inline code spans only + sub outside_code { + my ($line, $fn) = @_; + my @parts = split /(`[^`]*`)/, $line; + $_ = /^`/ ? $_ : $fn->($_) for @parts; + return join "", @parts; + } + while (my $line = ) { + chomp $line; + if ($in_code) { + print "$line\n"; + $prev = $line; + if ($line =~ /^```\s*$/) { $in_code = 0; $need_blank = 1 } + next; + } + if ($line =~ /^```/) { + $line = "```console" if $line =~ /^```\s*$/; + $need_blank = 1; + emit($line); + $in_code = 1; + next; + } + if ($line =~ /^\s*$/) { $need_blank = 1; next } + $line =~ s/^>\s*(?=\S)/> /; + $line =~ s{If you are using docker, use the image provided \[here\]\((https://hub\.docker\.com/[^)]+)\)}{If you are using Docker, use the [Clever Tools image from Docker Hub]($1)}; + $line = outside_code($line, sub { + my ($text) = @_; + $text =~ s/(?/`<$1>`/g; + $text =~ s{(?()]*[^\s<>().,;:!?])}{<$1>}g; + return $text; + }); + $need_blank = 1 if $line =~ /^- / && $prev ne "" && $prev !~ /^(- |\s)/; + emit($line); + } + ' < "${TMP}" +} > "${FILE}.new" + +mv "${FILE}.new" "${FILE}" +echo "${FILE} updated from Clever Tools ${VERSION}" From c7f1b8ff522c9e7156b16c2dc103d8ad0765f870 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 14:56:50 +0200 Subject: [PATCH 02/25] cli-reference: update to Clever Tools 5.0.0 --- content/doc/cli-reference.md | 292 +++++++++++++++++++++++++++++++++-- 1 file changed, 278 insertions(+), 14 deletions(-) diff --git a/content/doc/cli-reference.md b/content/doc/cli-reference.md index b1e36da65..e7fdce9d6 100644 --- a/content/doc/cli-reference.md +++ b/content/doc/cli-reference.md @@ -50,18 +50,55 @@ To control an application with Clever Tools, it must be linked to a local direct ## How to install Clever Tools -Clever Cloud CLI is based on Node.js. We thought it to be easily available on any platform. Thus, you can download Clever Tools as [a npm package](https://www.npmjs.com/package/clever-tools), but also through package managers or as a binary on many systems: +Clever Tools is available as a npm package, through package managers, or as a standalone binary on many systems: + +### Node.js + +Clever Tools is available as [a npm package](https://www.npmjs.com/package/clever-tools): + +#### npm + +```console +npm install -g clever-tools +``` + +#### pnpm + +```console +pnpm add -g clever-tools +``` + +#### Bun + +```console +bun add -g clever-tools +``` + +#### Yarn + +```console +yarn global add clever-tools +``` ### GNU/Linux #### Arch Linux (AUR) -If you use Arch Linux, install packages [from AUR](https://aur.archlinux.org/packages/clever-tools-bin/). If you don't know how to use this, run: +If you use Arch Linux, install Clever Tools from AUR. Two packages are available, they provide the same `clever` command and cannot be installed side by side: + +- [`clever-tools`](https://aur.archlinux.org/packages/clever-tools/): the Node.js flavor, it runs on the `nodejs` package of your system +- [`clever-tools-bin`](https://aur.archlinux.org/packages/clever-tools-bin/): a self-contained binary, with no runtime dependency + +If you use an AUR helper like `yay`, run: ```console -git clone https://aur.archlinux.org/clever-tools-bin.git clever-tools -cd clever-tools -makepkg -si +yay -S clever-tools +``` + +Or, for the self-contained binary: + +```console +yay -S clever-tools-bin ``` #### CentOS/Fedora (.rpm) @@ -288,7 +325,7 @@ clever accesslogs [options] -a, --alias Short name for the application --app Application to manage by its ID (or name, if unambiguous) --before, --until Fetch logs before this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h) --F, --format Output format (human, json, json-stream, clf) (default: human) +-F, --format Output format (clf only outputs HTTP access logs) (human, json, json-stream, clf) (default: human) ``` ## activity @@ -1214,28 +1251,255 @@ drain-id Drain ID **Usage** ```console -clever drain create [options] +clever drain create +``` + +#### drain create betterstack + +**Description:** Create a Better Stack drain + +**Since:** 4.11.0 + +**Usage** + +```console +clever drain create betterstack --source-token [options] ``` **Arguments** ```console -drain-type Drain type (betterstack, datadog, elasticsearch, newrelic, ovh-tcp, raw-http, syslog-tcp, syslog-udp) drain-url Drain URL ``` **Options** ```console +-t, --source-token Source token (required) --addon Add-on ID or real ID -a, --alias Short name for the application --k, --api-key API key (for newrelic) --app Application to manage by its ID (or name, if unambiguous) --i, --index-prefix Optional index prefix (for elasticsearch), `logstash` value is used if not set --p, --password Basic auth password (for elasticsearch or raw-http) --s, --sd-params RFC5424 structured data parameters (for ovh-tcp), e.g.: `X-OVH-TOKEN=\"REDACTED\"` --t, --source-token Source token (for betterstack) --u, --username Basic auth username (for elasticsearch or raw-http) +``` + +#### drain create datadog + +**Description:** Create a Datadog drain + +**Since:** 0.9.0 + +**Usage** + +```console +clever drain create datadog [options] +``` + +**Arguments** + +```console +drain-url Drain URL +``` + +**Options** + +```console + --addon Add-on ID or real ID +-a, --alias Short name for the application + --app Application to manage by its ID (or name, if unambiguous) +``` + +#### drain create elasticsearch + +**Description:** Create an Elasticsearch drain + +**Since:** 0.9.0 + +**Usage** + +```console +clever drain create elasticsearch --index-prefix [options] +``` + +**Arguments** + +```console +drain-url Drain URL, must end with '/_bulk' +``` + +**Options** + +```console +-i, --index-prefix Index prefix, indexes are created as `-YYYY-MM-DD` (required) + --addon Add-on ID or real ID +-a, --alias Short name for the application + --app Application to manage by its ID (or name, if unambiguous) +-p, --password Basic auth password +-u, --username Basic auth username +``` + +#### drain create newrelic + +**Description:** Create a New Relic drain + +**Since:** 0.9.0 + +**Usage** + +```console +clever drain create newrelic --api-key [options] +``` + +**Arguments** + +```console +drain-url Drain URL +``` + +**Options** + +```console +-k, --api-key API key (required) + --addon Add-on ID or real ID +-a, --alias Short name for the application + --app Application to manage by its ID (or name, if unambiguous) +``` + +#### drain create ovh-tcp + +**Description:** Create an OVH TCP drain + +**Since:** 0.9.0 + +**Usage** + +```console +clever drain create ovh-tcp [options] +``` + +**Arguments** + +```console +drain-url Drain URL +``` + +**Options** + +```console + --addon Add-on ID or real ID +-a, --alias Short name for the application + --app Application to manage by its ID (or name, if unambiguous) +-s, --sd-params RFC5424 structured data parameters, e.g.: `token=\"REDACTED\"` +``` + +#### drain create raw-http + +**Description:** Create a raw HTTP drain + +**Since:** 0.9.0 + +**Usage** + +```console +clever drain create raw-http [options] +``` + +**Arguments** + +```console +drain-url Drain URL +``` + +**Options** + +```console + --addon Add-on ID or real ID +-a, --alias Short name for the application + --app Application to manage by its ID (or name, if unambiguous) +-p, --password Basic auth password +-u, --username Basic auth username +``` + +#### drain create splunk + +**Description:** Create a Splunk HEC drain + +**Since:** 5.0.0 + +**Usage** + +```console +clever drain create splunk --hec-token [options] +``` + +**Arguments** + +```console +drain-url Drain URL +``` + +**Options** + +```console + --hec-token HTTP Event Collector token (required) + --addon Add-on ID or real ID +-a, --alias Short name for the application + --app Application to manage by its ID (or name, if unambiguous) + --index Optional target index, the HEC token's own index is used if not set + --sourcetype Optional sourcetype, the HEC token's own sourcetype is used if not set + --tls-verification TLS verification mode, use `trustful` to accept a self-signed certificate (default, trustful) +``` + +#### drain create syslog-tcp + +**Description:** Create a Syslog TCP drain + +**Since:** 0.9.0 + +**Usage** + +```console +clever drain create syslog-tcp [options] +``` + +**Arguments** + +```console +drain-url Drain URL +``` + +**Options** + +```console + --addon Add-on ID or real ID +-a, --alias Short name for the application + --app Application to manage by its ID (or name, if unambiguous) +-s, --sd-params RFC5424 structured data parameters, e.g.: `token=\"REDACTED\"` +``` + +#### drain create syslog-udp + +**Description:** Create a Syslog UDP drain + +**Since:** 0.9.0 + +**Usage** + +```console +clever drain create syslog-udp [options] +``` + +**Arguments** + +```console +drain-url Drain URL +``` + +**Options** + +```console + --addon Add-on ID or real ID +-a, --alias Short name for the application + --app Application to manage by its ID (or name, if unambiguous) +-s, --sd-params RFC5424 structured data parameters, e.g.: `token=\"REDACTED\"` ``` ### drain disable From 22f71223c356b16e981db3b2d0dc42d24ff99db4 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:00:05 +0200 Subject: [PATCH 03/25] manage(cli): document per-type drain creation, drain check, Better Stack and Splunk --- content/doc/manage/cli/logs-drains.md | 130 +++++++++++++++++++------- 1 file changed, 94 insertions(+), 36 deletions(-) diff --git a/content/doc/manage/cli/logs-drains.md b/content/doc/manage/cli/logs-drains.md index fc2ae2ce1..59aad924a 100644 --- a/content/doc/manage/cli/logs-drains.md +++ b/content/doc/manage/cli/logs-drains.md @@ -21,66 +21,124 @@ You can use Clever Tools to control logs drains, through following commands. Eac ```console clever drain clever drain -F json -clever drain create -clever drain get -clever drain get --format json -clever drain remove -clever drain enable -clever drain disable +clever drain create DRAIN_TYPE DRAIN_URL +clever drain get DRAIN_ID +clever drain get DRAIN_ID --format json +clever drain check DRAIN_ID +clever drain remove DRAIN_ID +clever drain enable DRAIN_ID +clever drain disable DRAIN_ID ``` All drain subcommands also accept `--addon ADDON_ID_OR_REAL_ID` to target an add-on instead of an application. The `--addon` option is mutually exclusive with `--app` and `--alias`. ```console clever drain --addon postgresql_xxxxxxxx -clever drain create --addon postgresql_xxxxxxxx raw-http https://logs.example.com -clever drain get --addon postgresql_xxxxxxxx -clever drain remove --addon postgresql_xxxxxxxx +clever drain create raw-http https://logs.example.com --addon postgresql_xxxxxxxx +clever drain get DRAIN_ID --addon postgresql_xxxxxxxx +clever drain remove DRAIN_ID --addon postgresql_xxxxxxxx ``` The `clever drain` command lists all drains for the target application or add-on and shows key metrics for each one. The `clever drain get` command displays detailed metrics for a single drain, including message output rate, throughput (with dynamic units), backlog size, retry attempts, and last error. These metrics help you monitor drain health and troubleshoot delivery issues. -Where `DRAIN-TYPE` is one of: +Once a drain exists, `clever drain check DRAIN_ID` verifies that its recipient is reachable and accepts deliveries. Add `--format json` to get the result in a machine-readable format. -- `datadog`: 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) -- `newrelic`: for NewRelic endpoint (note that this endpoint needs your NewRelic API Key) -- `ovh-tcp`: for OVH TCP syslog endpoint (note that this endpoint has an optional sd-params parameter) -- `raw-http`: for HTTP endpoint (note that this endpoint has optional username/password parameters as HTTP Basic Authentication) -- `syslog-tcp`: for TCP syslog endpoint -- `syslog-udp`: for UDP syslog endpoint +## Drain types -Drain creation supports the following options: +There is one `clever drain create` subcommand per drain type. Each one only accepts the options its drain type supports, and checks the required ones before any API call: -```console -[--username, -u] USERNAME Basic auth username (for elasticsearch or raw-http) -[--password, -p] PASSWORD Basic auth password (for elasticsearch or raw-http) -[--api-key, -k] API_KEY API key (for newrelic) -[--index-prefix, -i] INDEX_PREFIX Optional index prefix (for elasticsearch), `logstash` value is used if not set -[--sd-params, -s] SD_PARAMS RFC5424 structured data parameters (for ovh-tcp), e.g.: `X-OVH-TOKEN=\"REDACTED\"` -``` +| Drain type | Required option | Optional options | +|-----------------|----------------------------|----------------------------------------------------| +| `betterstack` | `--source-token`, `-t` | None | +| `datadog` | None | None | +| `elasticsearch` | `--index-prefix`, `-i` | `--password`, `-p`, `--username`, `-u` | +| `newrelic` | `--api-key`, `-k` | None | +| `ovh-tcp` | None | `--sd-params`, `-s` | +| `raw-http` | None | `--password`, `-p`, `--username`, `-u` | +| `splunk` | `--hec-token` | `--index`, `--sourcetype`, `--tls-verification` | +| `syslog-tcp` | None | `--sd-params`, `-s` | +| `syslog-udp` | None | `--sd-params`, `-s` | + +Run `clever drain create DRAIN_TYPE --help` to list the options of a drain type, or read the [CLI reference](/doc/cli-reference/#drain-create). + +## Better Stack logs drains -## ElasticSearch logs drains +To create a [Better Stack](https://betterstack.com/docs/logs/http-rest-api/) drain, use the ingesting host of your source, along with its source token: -ElasticSearch drains use the Elastic bulk API. To match this endpoint, specify `/_bulk` at the end of your ElasticSearch endpoint. +```bash +clever drain create betterstack "https://$BETTERSTACK_INGESTING_HOST" --source-token "$BETTERSTACK_SOURCE_TOKEN" +``` ## Datadog logs drains -Datadog has two zones, EU and COM. An account on one zone is not available on the other, make sure to target the good EU or COM intake endpoint. To create a [Datadog](https://docs.datadoghq.com/api/?lang=python#send-logs-over-http) drain, you just need to use one of the following command depending on your zone: +[Datadog](https://docs.datadoghq.com/api/?lang=python#send-logs-over-http) accounts belong to a [Datadog site](https://docs.datadoghq.com/getting_started/site/). An account on one site isn't available on the others, so make sure you target the intake endpoint of your site. These examples target EU1 and US1: -```console +```bash # EU -clever drain create datadog "https://http-intake.logs.datadoghq.eu/v1/input/?ddsource=clevercloud&service=&host=" +clever drain create datadog "https://http-intake.logs.datadoghq.eu/v1/input/$DATADOG_API_KEY?ddsource=clevercloud&service=myapp" # US -clever drain create datadog "https://http-intake.logs.datadoghq.com/v1/input/?ddsource=clevercloud&service=&host=" +clever drain create datadog "https://http-intake.logs.datadoghq.com/v1/input/$DATADOG_API_KEY?ddsource=clevercloud&service=myapp" ``` -The `host` query parameter is not mandatory: in the Datadog pipeline configuration, you can map `@source_host` which is the host provided by Clever Cloud in logs as `host` property. +You can add a `host` query parameter to the URL, but it's not mandatory: in the Datadog pipeline configuration, you can map `@source_host`, the host provided by Clever Cloud in logs, as the `host` property. -## NewRelic logs drains +## Elasticsearch logs drains -NewRelic has two zones, EU and US. An account on one zone is not available on the other, make sure to target the good EU or US intake endpoint. To create a [NewRelic](https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/) drain, you just need to use: +Elasticsearch drains use the Elastic bulk API, so the drain URL must end with `/_bulk`. The `--index-prefix` option is required: logs go to a daily index named `INDEX_PREFIX-YYYY-MM-DD`. For example, with the credentials of a Clever Cloud Elasticsearch add-on: -```console -clever drain create newrelic "https://log-api.eu.newrelic.com/log/v1" --api-key +```bash +clever drain create elasticsearch "https://$ES_ADDON_HOST/_bulk" --index-prefix logstash --username "$ES_ADDON_USER" --password "$ES_ADDON_PASSWORD" +``` + +The `--username` and `--password` options are optional, use them when your cluster requires basic authentication. + +## New Relic logs drains + +[New Relic](https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/) has two zones, EU and US. An account on one zone isn't available on the other, so make sure you target the right intake endpoint (`log-api.eu.newrelic.com` or `log-api.newrelic.com`): + +```bash +clever drain create newrelic https://log-api.eu.newrelic.com/log/v1 --api-key "$NEW_RELIC_API_KEY" +``` + +## OVH TCP logs drains + +OVH TCP drains are syslog drains sent over TCP to an [OVHcloud Logs Data Platform](/doc/develop/observability/drains/#ovhcloud-logs-data-platform) endpoint. Pass the write token of your stream as an RFC5424 structured data parameter: + +```bash +clever drain create ovh-tcp "tcp://$LDP_HOST:514" --sd-params "X-OVH-TOKEN=\"$LDP_WRITE_TOKEN\"" +``` + +## Raw HTTP logs drains + +Raw HTTP drains send log batches as JSON `POST` requests to any HTTP endpoint. Basic authentication is optional: + +```bash +clever drain create raw-http https://logs.example.com/clever-cloud +clever drain create raw-http https://logs.example.com/clever-cloud --username "$DRAIN_USERNAME" --password "$DRAIN_PASSWORD" +``` + +## Splunk logs drains + +Splunk drains send events to the [HTTP Event Collector](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector) (HEC). The drain URL is the full collector endpoint, and the token is the one bound to your HEC input: + +```bash +clever drain create splunk https://splunk.example.com:8088/services/collector/event --hec-token "$SPLUNK_HEC_TOKEN" +``` + +The `--index` and `--sourcetype` options are optional. When you don't set them, the values configured on the HEC token apply. When you set them, they override these values for every forwarded event. + +A self-hosted Splunk instance ships a self-signed certificate on port `8088` by default. If you didn't replace it, add `--tls-verification trustful` so the drain doesn't fail on certificate verification. Without it, the drain fully verifies the certificate: + +```bash +clever drain create splunk https://splunk.example.com:8088/services/collector/event --hec-token "$SPLUNK_HEC_TOKEN" --tls-verification trustful +``` + +## Syslog logs drains + +Syslog drains forward logs in the RFC5424 format, over a TCP connection with `syslog-tcp`, or over UDP with `syslog-udp`, which means without any delivery guarantee. Use `--sd-params` when your collector expects structured data parameters, such as an authentication token: + +```bash +clever drain create syslog-tcp tcp://logs.example.com:514 +clever drain create syslog-tcp tcp://logs.example.com:514 --sd-params "token=\"$SYSLOG_TOKEN\"" +clever drain create syslog-udp udp://logs.example.com:514 ``` From cd45422f9e5724993059f9305e0023ba44e49a78 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:00:05 +0200 Subject: [PATCH 04/25] develop(drains): align CLI examples with Clever Tools 5.0 and add Better Stack and Splunk --- content/doc/develop/observability/drains.md | 87 ++++++++++++--------- 1 file changed, 51 insertions(+), 36 deletions(-) diff --git a/content/doc/develop/observability/drains.md b/content/doc/develop/observability/drains.md index 979c40b6f..243666902 100644 --- a/content/doc/develop/observability/drains.md +++ b/content/doc/develop/observability/drains.md @@ -3,13 +3,15 @@ type: docs weight: 40 linkTitle: Drains title: Log Drains -description: Forward your application logs to Elasticsearch, Datadog, New Relic, OVHcloud or any HTTP endpoint with log drains +description: Forward your application logs to Better Stack, Elasticsearch, Datadog, New Relic, OVHcloud, Splunk or any HTTP endpoint with log drains keywords: - log drains - elasticsearch +- better stack - datadog - newrelic - ovhcloud +- splunk - export aliases: - /doc/administrate/log-drains @@ -19,45 +21,48 @@ aliases: You can use log drains to send your application's [logs](/doc/develop/observability/logs) to an external server with the following command. -```bash -clever drain create [--alias ] [--username ] [--password ] +```console +clever drain create DRAIN_TYPE DRAIN_URL ``` Where `DRAIN-TYPE` is one of: -- `syslog-tcp`: for TCP syslog endpoint; -- `syslog-udp`: for UDP syslog endpoint; -- `raw-http`: for HTTP 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); -- `datadog`: for Datadog endpoint (note that this endpoint needs your Datadog API Key); -- `newrelic`: for NewRelic endpoint (note that this endpoint needs your NewRelic API Key); -- `ovh-tcp`: for OVH TCP syslog endpoint (note that this endpoint has an optional sd-params parameter). +- `betterstack`: for Better Stack endpoint (note that this endpoint needs your source token) +- `datadog`: for Datadog endpoint (note that this endpoint needs your Datadog API Key in its URL) +- `elasticsearch`: for Elasticsearch endpoint (note that this endpoint needs an index prefix, and has optional username/password parameters as HTTP Basic Authentication) +- `newrelic`: for New Relic endpoint (note that this endpoint needs your New Relic API Key) +- `ovh-tcp`: for OVH TCP syslog endpoint (note that this endpoint has an optional sd-params parameter) +- `raw-http`: for HTTP endpoint (note that this endpoint has optional username/password parameters as HTTP Basic Authentication) +- `splunk`: for Splunk HTTP Event Collector endpoint (note that this endpoint needs your HEC token) +- `syslog-tcp`: for TCP syslog endpoint +- `syslog-udp`: for UDP syslog endpoint -You can list the currently activated drains with this command. +Each drain type has its own options, listed in the [Clever Tools logs drains documentation](/doc/manage/cli/logs-drains/). Add `--alias ALIAS` or `--app APP_ID_OR_NAME` to target a specific application. You can list the currently activated drains with this command. -```bash -clever drain [--alias ] +```console +clever drain ``` -And remove them if needed +Check that the recipient of a drain is reachable and accepts deliveries, and remove it if needed: -```bash -clever drain remove [--alias ] +```console +clever drain check DRAIN_ID +clever drain remove DRAIN_ID ``` If the status of your drain appears as `DISABLED` without you disabling it, it may be because it haven't been able to send your application logs to your drain endpoint or because the requests timed out after **25 seconds**. -Use the logs drain to send your add-on's logs by using `--addon` flag, the value must be the add-on ID starting by `addon_`. +Use the logs drain to send your add-on's logs by using `--addon` flag, the value must be the add-on ID starting by `addon_`, or its real ID such as `postgresql_xxxxxxxx`. ## Elasticsearch -Elasticsearch drains use the Elastic bulk API. To match this endpoint, specify `/_bulk` at the end of your Elasticsearch endpoint. +Elasticsearch drains use the Elastic bulk API. To match this endpoint, specify `/_bulk` at the end of your Elasticsearch endpoint, and set an index prefix with `--index-prefix`. For example, with the credentials of a Clever Cloud Elasticsearch add-on: ```bash -clever drain create elasticsearch https://xxx-elasticsearch.services.clever-cloud.com/_bulk --username USERNAME --password PASSWORD +clever drain create elasticsearch "https://$ES_ADDON_HOST/_bulk" --index-prefix logstash --username "$ES_ADDON_USER" --password "$ES_ADDON_PASSWORD" ``` -Each day, we will create an index `logstash-` and push logs to it. +Each day, the drain creates an index named after this prefix, `logstash-YYYY-MM-DD` in this example, and pushes logs to it. ### Index Lifecycle Management @@ -105,14 +110,14 @@ For more information, please refer to the [official documentation](https://www.e ## Datadog -To create a [Datadog](https://docs.datadoghq.com/fr/api/latest/logs/#send-logs) drain, you just need to use: +To create a [Datadog](https://docs.datadoghq.com/api/latest/logs/#send-logs) drain, use your Datadog API key in the intake URL: ```bash -clever drain create datadog "https://http-intake.logs.datadoghq.com/v1/input/?ddsource=clevercloud&service=&hostname=" +clever drain create datadog "https://http-intake.logs.datadoghq.com/v1/input/$DATADOG_API_KEY?ddsource=clevercloud&service=myapp" ``` {{< callout type="warning" >}} -Datadog has two zones, **EU** and **COM**. An account on one zone is not available on the other, make sure to target the right intake endpoint (`datadoghq.eu` or `datadoghq.com`). +Datadog accounts belong to a [Datadog site](https://docs.datadoghq.com/getting_started/site/), such as US1 (`datadoghq.com`) or EU1 (`datadoghq.eu`). An account on one site isn't available on the others, so make sure to target the intake endpoint of your site. {{< /callout >}} ## NewRelic @@ -120,13 +125,31 @@ Datadog has two zones, **EU** and **COM**. An account on one zone is not availab To create a [NewRelic](https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/) drain, use: ```bash -clever drain create newrelic "https://log-api.eu.newrelic.com/log/v1" --api-key "" +clever drain create newrelic https://log-api.eu.newrelic.com/log/v1 --api-key "$NEW_RELIC_API_KEY" ``` {{< callout type="warning" >}} NewRelic has two zones, **EU** and **US**. An account on one zone is not available on the other, make sure to target the right intake endpoint (`log-api.eu.newrelic.com` or `log-api.newrelic.com`). {{< /callout >}} +## Better Stack + +To create a [Better Stack](https://betterstack.com/docs/logs/http-rest-api/) drain, use the ingesting host of your source, along with its source token: + +```bash +clever drain create betterstack "https://$BETTERSTACK_INGESTING_HOST" --source-token "$BETTERSTACK_SOURCE_TOKEN" +``` + +## Splunk + +To send logs to a Splunk [HTTP Event Collector](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector) (HEC), use the full collector endpoint and the token bound to your HEC input: + +```bash +clever drain create splunk https://splunk.example.com:8088/services/collector/event --hec-token "$SPLUNK_HEC_TOKEN" +``` + +The `--index` and `--sourcetype` options override the values configured on the HEC token. If your self-hosted Splunk instance still uses its default self-signed certificate, add `--tls-verification trustful`. + ## OVHcloud Logs Data Platform To export logs from an application or an add-on to [OVHcloud Logs Data Platform](https://help.ovhcloud.com/csm/en-ie-logs-data-platform-quick-start?id=kb_article_view&sysparm_article=KB0055819), use the following setup: @@ -142,28 +165,20 @@ On your terminal, use the following command: {{< tab name="Application" >}}**Exporting logs from an application**: ```shell - clever drain create ovh-tcp tcp://:514 -app --sd-params="X-OVH-TOKEN=\"\"" + clever drain create ovh-tcp "tcp://$LDP_HOST:514" --app APP_ID_OR_NAME --sd-params "X-OVH-TOKEN=\"$LDP_WRITE_TOKEN\"" ``` - Replace the following values: - -- `` -- `` -- `` + Set `LDP_HOST` to your Logs Data Platform host and `LDP_WRITE_TOKEN` to the write token of your stream, then replace `APP_ID_OR_NAME` with your application ID or name. {{< /tab >}} {{< tab name="Add-on" >}}**Exporting logs from an add-on**: ```shell - clever drain create ovh-tcp tcp://:514 -addon --sd-params="X-OVH-TOKEN=\"\"" + clever drain create ovh-tcp "tcp://$LDP_HOST:514" --addon ADDON_ID --sd-params "X-OVH-TOKEN=\"$LDP_WRITE_TOKEN\"" ``` - Replace the following values: - -- `` -- `` -- `` + Set `LDP_HOST` to your Logs Data Platform host and `LDP_WRITE_TOKEN` to the write token of your stream, then replace `ADDON_ID` with your add-on ID or real ID. {{< /tab >}} From e3f75eca9198208575ffef28980a6f10fc2b6504 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:01:38 +0200 Subject: [PATCH 05/25] manage(cli): add Node.js package managers, both AUR packages and an update guide --- content/doc/manage/cli/install/_index.md | 60 ++++++++-- content/doc/manage/cli/install/update.md | 140 +++++++++++++++++++++++ 2 files changed, 192 insertions(+), 8 deletions(-) create mode 100644 content/doc/manage/cli/install/update.md diff --git a/content/doc/manage/cli/install/_index.md b/content/doc/manage/cli/install/_index.md index ef072ba06..3fca6c481 100644 --- a/content/doc/manage/cli/install/_index.md +++ b/content/doc/manage/cli/install/_index.md @@ -19,8 +19,13 @@ aliases: - /doc/install --- -Clever Cloud CLI is based on Node.js. We thought it to be easily available on any platform. Thus, you can download Clever Tools as [a npm package](https://www.npmjs.com/package/clever-tools), but also through package managers or as a binary on many systems: +Clever Tools is available as a npm package, through package managers, or as a standalone binary on many systems: +- [Node.js](#nodejs) + - [npm](#npm) + - [pnpm](#pnpm) + - [Bun](#bun) + - [Yarn](#yarn) - [GNU/Linux](#gnulinux) - [Arch Linux (AUR)](#arch-linux-aur) - [CentOS/Fedora (.rpm)](#centosfedora-rpm) @@ -38,16 +43,55 @@ Clever Cloud CLI is based on Node.js. We thought it to be easily available on an - [Nix package manager](#nix-package-manager) - [Enabling autocompletion](#enabling-autocompletion) +To upgrade an existing installation, follow the [update guide](/doc/manage/cli/install/update/). + +## Node.js + +Clever Tools is available as [a npm package](https://www.npmjs.com/package/clever-tools), which requires Node.js 24 or later. Install it globally with the package manager you use. + +### npm + +```bash +npm install -g clever-tools +``` + +### pnpm + +```bash +pnpm add -g clever-tools +``` + +### Bun + +```bash +bun add -g clever-tools +``` + +### Yarn + +```bash +yarn global add clever-tools +``` + ## GNU/Linux ### Arch Linux (AUR) -If you use Arch Linux, install packages [from AUR](https://aur.archlinux.org/packages/clever-tools-bin/). If you don't know how to use this, run: +If you use Arch Linux, install Clever Tools from AUR. Two packages are available. They provide the same `clever` command, so you can't install both side by side: -```console -git clone https://aur.archlinux.org/clever-tools-bin.git clever-tools -cd clever-tools -makepkg -si +- [`clever-tools`](https://aur.archlinux.org/packages/clever-tools/): the Node.js flavor, it runs on the `nodejs` package of your system +- [`clever-tools-bin`](https://aur.archlinux.org/packages/clever-tools-bin/): a self-contained binary, with no runtime dependency + +If you use an AUR helper like `yay`, run: + +```bash +yay -S clever-tools +``` + +Or, for the self-contained binary: + +```bash +yay -S clever-tools-bin ``` ### CentOS/Fedora (.rpm) @@ -103,7 +147,7 @@ cp clever-tools-latest_linux/clever ~/.local/bin/ ## macOS -We only provide macOS packages for Apple Silicon processors. On an Intel Mac, prefer using `npm` release. +Clever Tools only provides macOS binaries for Apple Silicon processors. On an Intel Mac, use the [npm package](#nodejs). ### Homebrew @@ -157,7 +201,7 @@ If you are using Docker, use the [Clever Tools image from Docker Hub](https://hu ```console docker pull clevercloud/clever-tools -docker run --rm clever-tools +docker run --rm clevercloud/clever-tools version ``` ### Dockerfile diff --git a/content/doc/manage/cli/install/update.md b/content/doc/manage/cli/install/update.md new file mode 100644 index 000000000..6dafeeb9c --- /dev/null +++ b/content/doc/manage/cli/install/update.md @@ -0,0 +1,140 @@ +--- +type: docs +weight: 1 +linkTitle: Update Clever Tools +title: Update Clever Tools +description: Update Clever Tools CLI to its latest version with npm, pnpm, Bun, Yarn, AUR, rpm, deb, Homebrew, WinGet, Docker, Nix or standalone binaries +keywords: +- update +- upgrade +- clever-tools +- cli +- version +--- + +Clever Tools notifies you when a new version is available. The command to update it depends on how you installed it. If you're not sure, see [how to install Clever Tools](/doc/manage/cli/install/). Once updated, check the installed version: + +```bash +clever version +``` + +## Node.js + +The npm package requires Node.js 24 or later, upgrade Node.js first if needed. + +### npm + +```bash +npm install -g clever-tools +``` + +### pnpm + +```bash +pnpm add -g clever-tools +``` + +### Bun + +```bash +bun add -g clever-tools +``` + +### Yarn + +```bash +yarn global add clever-tools +``` + +## GNU/Linux + +### Arch Linux (AUR) + +With an AUR helper like `yay`, update the package you installed. For [`clever-tools`](https://aur.archlinux.org/packages/clever-tools/), the Node.js flavor, run: + +```bash +yay -S clever-tools +``` + +For [`clever-tools-bin`](https://aur.archlinux.org/packages/clever-tools-bin/), the self-contained binary, run: + +```bash +yay -S clever-tools-bin +``` + +### CentOS/Fedora (.rpm) + +```bash +yum update clever-tools +``` + +### Debian/Ubuntu (.deb) + +```bash +apt update +apt install --only-upgrade clever-tools +``` + +### Exherbo + +```bash +cave sync +cave resolve clever-tools-bin -zx +``` + +### Other distributions (.tar.gz) + +Download the latest archive again and replace the binary in your `PATH`: + +```bash +curl -O https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_linux.tar.gz +tar xvzf clever-tools-latest_linux.tar.gz +cp clever-tools-latest_linux/clever ~/.local/bin/ +``` + +## macOS + +### Homebrew + +```bash +brew upgrade CleverCloud/homebrew-tap/clever-tools +``` + +### Binary (.tar.gz) + +Download the latest archive again and replace the binary in your `PATH`: + +```bash +curl -O https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_macos.tar.gz +tar xvzf clever-tools-latest_macos.tar.gz +cp clever-tools-latest_macos/clever ~/.local/bin/ +``` + +## Windows + +### WinGet + +```PowerShell +winget upgrade CleverTools +``` + +### Binary (.zip) + +Download the latest archive again and replace the binary in your `PATH`: + +```PowerShell +Invoke-WebRequest https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_win.zip -OutFile clever-tools-latest_win.zip +Expand-Archive .\clever-tools-latest_win.zip -DestinationPath . -Force +``` + +## Docker + +Pull the image again to get the latest tag: + +```bash +docker pull clevercloud/clever-tools +``` + +## Nix package manager + +Update your channel or flake input, then upgrade the package as usual for your setup. See [the Clever Tools package on NixOS Search](https://search.nixos.org/packages?channel=unstable&show=clever-tools&from=0&size=50&sort=relevance&type=packages&query=clever-tools). From 7eac4193c6ddee8429d71d14c7c33acb2c888c6c Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:03:31 +0200 Subject: [PATCH 06/25] manage(cli): document TLS certificates, HTTP proxy, system Git by default and login fallback --- content/doc/manage/cli/_index.md | 94 +++++++++++++++++++++++++++++++- 1 file changed, 93 insertions(+), 1 deletion(-) diff --git a/content/doc/manage/cli/_index.md b/content/doc/manage/cli/_index.md index e5ada49d4..b518d9dfa 100644 --- a/content/doc/manage/cli/_index.md +++ b/content/doc/manage/cli/_index.md @@ -83,6 +83,92 @@ For each of them, you can add these parameters: > [!TIP] > For commands returning a list of items, you can use `--format json` or `-F json` to get a JSON output. +## TLS certificates (corporate proxy / custom CA) + +Clever Tools verifies the TLS certificate of every HTTPS connection it makes, both for API calls and for Git-based deployments. Behind a corporate proxy that intercepts HTTPS, or when your endpoint relies on a private or self-signed Certificate Authority (CA), this verification can fail with an error such as: + +```text +Error: self signed certificate in certificate chain +``` + +The right fix is to make Clever Tools trust your CA, not to disable verification. There are two ways to do it, depending on whether your CA is installed system-wide or only available as a file. + +### Trust your operating system's certificate store + +If your corporate or proxy root CA is installed at the OS level (Windows Certificate Store, macOS Keychain, Linux `/etc/ssl/certs`), Clever Tools can rely on it. The binary already trusts the OS certificate store, there is nothing to do. The npm package runs on your own Node.js, so enable it explicitly: + +```bash +NODE_OPTIONS=--use-system-ca clever profile +``` + +If the CA isn't in the OS store yet, ask your IT team to install it there: other tools relying on the OS certificate store then trust it too, not only Clever Tools. + +### Trust a specific certificate + +When the CA is only available as a file, set the `NODE_EXTRA_CA_CERTS` environment variable to its path. This works the same way for both the binary and npm installs. The file must be PEM-encoded and may contain several certificates: + +{{< tabs >}} + {{< tab name="Linux / macOS" >}} + + ```bash + export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem + clever profile + ``` + + {{< /tab >}} + {{< tab name="Windows (PowerShell)" >}} + + ```powershell + $env:NODE_EXTRA_CA_CERTS = "C:\path\to\corporate-ca.pem" + clever profile + ``` + + {{< /tab >}} +{{< /tabs >}} + +Node.js reads `NODE_EXTRA_CA_CERTS` and `NODE_OPTIONS` at startup: set them in your shell, or inline before the command, not in a `.env` file. + +### Git-based deployments + +`clever deploy` pushes over HTTPS and verifies certificates too. By default, it delegates to your system `git` binary, which ignores `NODE_EXTRA_CA_CERTS` and follows its own TLS configuration: the OS certificate store (recommended), or an explicit CA file set with `git config --global http.sslCAInfo /path/to/corporate-ca.pem`, equivalent to the `GIT_SSL_CAINFO` environment variable. + +If you fall back to the previous JavaScript Git implementation (`clever features disable system-git`), Clever Tools handles Git operations on Node.js instead. It then trusts the OS certificate store and `NODE_EXTRA_CA_CERTS` exactly like API calls. + +Keep TLS verification enabled, and install your CA in the trust store each client uses: the OS certificate store for the binary, the same store with `NODE_OPTIONS=--use-system-ca` for npm installs, and the store or CA file configured for your system Git, depending on its TLS backend. Disabling TLS verification entirely, for example with `NODE_TLS_REJECT_UNAUTHORIZED=0`, exposes you to man-in-the-middle attacks, including the theft of your Clever Cloud credentials. + +## HTTP proxy + +On a network where outgoing traffic must go through an HTTP proxy, Clever Tools follows the `http_proxy` and `https_proxy` environment variables. Set them in your shell, and Clever Tools routes its API calls and update checks through the proxy: + +{{< tabs >}} + {{< tab name="Linux / macOS" >}} + + ```bash + export http_proxy=http://proxy.example.com:3128 + export https_proxy=http://proxy.example.com:3128 + clever profile + ``` + + {{< /tab >}} + {{< tab name="Windows (PowerShell)" >}} + + ```powershell + $env:http_proxy = "http://proxy.example.com:3128" + $env:https_proxy = "http://proxy.example.com:3128" + clever profile + ``` + + {{< /tab >}} +{{< /tabs >}} + +Clever Tools also recognizes the uppercase variants, `HTTP_PROXY` and `HTTPS_PROXY`. For a proxy that requires authentication, set credentials in the URL, such as `http://user:password@proxy.example.com:3128`. To bypass the proxy for some hosts, list them in the `no_proxy` (or `NO_PROXY`) variable: + +```bash +export no_proxy=localhost,127.0.0.1,.internal.example.com +``` + +Like the TLS variables, Clever Tools reads proxy variables at startup: set them in your shell or inline before the command, not in a `.env` file. By default, `clever deploy` delegates to your system `git`, which follows its own proxy configuration: `git config --global http.proxy`, or the same `http_proxy` and `https_proxy` variables. The previous JavaScript Git implementation, used when you disable `system-git`, doesn't go through this proxy. + ## features Some features are available as experimental, before they're completely ready for prime time. They usually work well, but this testing phase allows us to get feedbacks, refine some details, documentation, and break things between two releases. @@ -106,6 +192,12 @@ To get information about how to use an experimental feature, use: clever features info theFeature ``` +A feature can also graduate to stable and become enabled by default, while you can still disable it. Since Clever Tools 5.0.0, it's the case of `system-git`, which makes Git operations use the `git` installed on your system instead of a pure JavaScript implementation. Disable it if `git` isn't available in your `PATH`: + +```console +clever features disable system-git +``` + ## diag | version To check the current version or get information about your setup, use: @@ -127,7 +219,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 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. +It opens your default browser and starts 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 automatically stores these `token` and `secret` values in a hidden `clever-tools.json` config file in the current local user home folder. If Clever Tools can't open a browser, for example on a headless system, it prints a warning with the URL to open and keeps waiting for you to complete the login. If you already know them, you can use: From 31dcacf967f71ca58a4b1a9fdc92db2162fe5a08 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:06:13 +0200 Subject: [PATCH 07/25] manage(cli): document system Git deploys, ssh commands and TCP and SSH access logs --- .../cli/applications/deployment-lifecycle.md | 28 +++++++++++++++---- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/content/doc/manage/cli/applications/deployment-lifecycle.md b/content/doc/manage/cli/applications/deployment-lifecycle.md index ded7f7a92..792792836 100644 --- a/content/doc/manage/cli/applications/deployment-lifecycle.md +++ b/content/doc/manage/cli/applications/deployment-lifecycle.md @@ -47,6 +47,14 @@ It will `git push` your code on the remote repository of your application on Cle > [!TIP] > You can cancel a deployment with `clever cancel-deploy` command. You can also [configure an application](/doc/manage/cli/applications/configuration/#config) so that a new deployment cancels the current one. +Since Clever Tools 5.0.0, `clever deploy` uses the `git` command installed on your system, which must be available in your `PATH`. If `git` isn't available, or if you experience an issue with this backend, fall back to the previous pure JavaScript implementation. It works without `git` installed on your system, but it only supports HTTP, slows down on repositories with rewritten history, can time out on large repositories or big files, and can't deploy from a linked Git worktree: + +```console +clever features disable system-git +``` + +To switch back to the system Git backend, use `clever features enable system-git`. + ## console | open Once deployed, you can open the application on your default browser or [Clever Cloud Console](https://console.clever-cloud.com): @@ -93,10 +101,18 @@ clever cancel-deploy ## ssh -A Clever Cloud application is a running virtual machine you can ssh to, as a user (`bas`). By default, it will use `OpenSSH` configuration, but you can target a specific identity file: +A Clever Cloud application is a running virtual machine you can ssh to, as a user (`bas`). Clever Cloud only accepts SSH key authentication, so Clever Tools disables the password fallback: a missing or unregistered key fails immediately. By default, it uses your `OpenSSH` configuration, but you can target a specific identity file. Clever Tools then also sets `IdentitiesOnly=yes`, so SSH doesn't offer unrelated keys from your agent, while `IdentityFile` entries of your SSH configuration still apply: ```console -clever ssh [--identity-file, -i] IDENTITY-FILE +clever ssh --identity-file ~/.ssh/id_ed25519 +``` + +If your application runs several instances, Clever Tools asks you which one to connect to. This selection needs an interactive terminal: without one, the command fails when several instances are running. + +To execute a single command on the remote instance and exit, use `--command` (`-c`). Its output streams to your terminal without the SSH gateway messages, so you can use it in scripts: + +```console +clever ssh --command "ls -la" ``` To ssh a specific application, use: @@ -120,7 +136,7 @@ You can also get logs from a specific timeline, deployment or add-on through opt [--after, --since] AFTER Fetch logs after this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h) [--search] SEARCH Fetch logs matching this pattern [--deployment-id] DEPLOYMENT_ID Fetch logs for a given deployment -[--addon] ADDON_ID Add-on ID +[--addon] ADDON_ID Add-on ID or real ID [--format, -F] FORMAT Output format (human, json, json-stream) (default: human) ``` @@ -135,14 +151,16 @@ 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: +You can also get access logs from a specific timeline through options, in multiple formats: ```console [--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 date, positive number in seconds or duration, e.g.: 1h) -[--format, -F] FORMAT Output format (human, json, json-stream) (default: human) +[--format, -F] FORMAT Output format (human, json, json-stream, clf) (default: human) ``` +Besides HTTP requests, access logs include TCP redirections and SSH connections to your instances. In the `human` format, a column shows the transport of each line, `HTTP`, `TCP` or `SSH`, and HTTP methods and paths get their own columns so they stay aligned. The `clf` format, for Common Log Format, only outputs HTTP access logs. + You can for example get access logs in JSON stream format for the last hour with: ```console From 8284da75705b8c180c612ec1ba61a711128be185 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:06:13 +0200 Subject: [PATCH 08/25] manage(cli): show the domain add and rm commands instead of their descriptions --- content/doc/manage/cli/applications/configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/doc/manage/cli/applications/configuration.md b/content/doc/manage/cli/applications/configuration.md index b7db48dda..8dab479c5 100644 --- a/content/doc/manage/cli/applications/configuration.md +++ b/content/doc/manage/cli/applications/configuration.md @@ -110,8 +110,8 @@ clever domain overview --filter .tld --format json To add/remove a domain to an application, use: ```console -add Add a domain name to a Clever Cloud application -rm Remove a domain name from a Clever Cloud application +clever domain add FQDN +clever domain rm FQDN ``` > [!TIP] From f2b7d45b29b1d6ba4654e98ca0ff010ffc74ce18 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:07:04 +0200 Subject: [PATCH 09/25] manage(cli): document organisation-scoped add-on providers and fix add-on command synopses --- content/doc/manage/cli/addons.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/content/doc/manage/cli/addons.md b/content/doc/manage/cli/addons.md index f781e4d8b..c1c4c33cf 100644 --- a/content/doc/manage/cli/addons.md +++ b/content/doc/manage/cli/addons.md @@ -15,12 +15,14 @@ aliases: - /doc/cli/addons --- -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 following commands, you can target a specific user/organisation: +Add-ons on Clever Cloud are databases, storage services, tools or third party services you can enable through `clever addon providers`. For each of the following commands, you can target a specific user/organisation: ```console [--org, -o, --owner] Organisation ID (or name, if unambiguous) ``` +`clever addon env` and `clever database backups` resolve the organisation of the add-on automatically, their `--org` option is deprecated. + ## list To list provisioned add-ons, use: @@ -40,6 +42,13 @@ clever addon providers clever addon providers show PROVIDER_NAME ``` +Providers, regions and plans can depend on the organisation. Add `--org` to only list what a given organisation can use: + +```console +clever addon providers --org ORG_ID_OR_NAME +clever addon providers show PROVIDER_NAME --org ORG_ID_OR_NAME +``` + ## create | rename | delete To create an add-on, select a provider and choose a name: @@ -48,6 +57,8 @@ To create an add-on, select a provider and choose a name: clever addon create PROVIDER ADDON_NAME ``` +When you set `--org`, Clever Tools checks that the requested region is available for this organisation before creating the add-on. + You can set `plan`, `region`, `version`, `option` and directly `link` an add-on to an application through these parameters: ```console @@ -72,7 +83,8 @@ clever addon rename ADDON_ID_OR_NAME ADDON_NEW_NAME To delete an add-on, use: ```console -clever addon delete [--yes, -y] ADDON_ID_OR_NAME +clever addon delete ADDON_ID_OR_NAME +clever addon delete ADDON_ID_OR_NAME --yes ``` ## env @@ -80,7 +92,8 @@ clever addon delete [--yes, -y] ADDON_ID_OR_NAME Each add-on comes with environment variables. To get them, use: ```console -clever addon env [--format, -F] FORMAT ADDON_ID +clever addon env ADDON_ID +clever addon env ADDON_ID --format json ``` > [!NOTE] @@ -142,13 +155,15 @@ clever config-provider open CONFIG_PROVIDER_ID_OR_NAME Databases are backup every day, with last 7 days of backups available to download. You can list them, available formats are: `human` (default) or `json`: ```console -clever database backups DATABASE-ID [--format, -F] FORMAT +clever database backups DATABASE_ID +clever database backups DATABASE_ID --format json ``` To download one of them, use: ```console -clever database backups download [--output, --out] OUTPUT_FILE DATABASE_ID BACKUP_ID +clever database backups download DATABASE_ID BACKUP_ID +clever database backups download DATABASE_ID BACKUP_ID --output OUTPUT_FILE ``` This command is still under development and will evolve over time. To get information about backups and download them, you can use our API and `clever curl`. For example: From 3dacbf9e2b70d2bf1d1fac96998bc30d890146ee Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:08:25 +0200 Subject: [PATCH 10/25] manage(cli): fix the Nexus key combination command and drop stale repository references --- content/doc/manage/cli/install/nexus-config.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/doc/manage/cli/install/nexus-config.md b/content/doc/manage/cli/install/nexus-config.md index 11c978ac8..a5f22139e 100644 --- a/content/doc/manage/cli/install/nexus-config.md +++ b/content/doc/manage/cli/install/nexus-config.md @@ -2,7 +2,7 @@ type: docs linkTitle: Nexus repository title: Nexus repository -description: Configure Clever Cloud Nexus repository for package distribution using .deb, .nupkg, and .rpm package formats +description: Configure Clever Cloud Nexus repository for package distribution using .deb and .rpm package formats keywords: - nexus - repository @@ -14,27 +14,27 @@ aliases: - /doc/cli/install/nexus-config --- -We use a self hosted Nexus repository to distribute `.deb` and `.rpm`. It's available at [https://nexus.clever-cloud.com/](https://nexus.clever-cloud.com/). +You can obtain Clever Tools `.deb` and `.rpm` packages from the [Clever Cloud Nexus repository](https://nexus.clever-cloud.com/). ## Repositories ### `.deb` repository -We provide a [Nexus repository for `.deb` packages](https://nexus.clever-cloud.com/#browse/browse:deb). +You can browse the [Nexus repository for `.deb` packages](https://nexus.clever-cloud.com/#browse/browse:deb). - stable: [deb](https://nexus.clever-cloud.com/#browse/browse:deb) -The repository is signed with the PGP key `Clever Cloud Nexus (deb)`. The public key is published on the Cellar at [https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key](https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key). The private key, public key and passphrase are stored in our vault. +The repository is signed with the PGP key `Clever Cloud Nexus (deb)`. The public key is published on the Cellar at [https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key](https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key). The private key, public key and passphrase are stored in the maintainer vault. ### `.rpm` repository -We provide a [Nexus repository for `.rpm` packages](https://nexus.clever-cloud.com/#browse/browse:rpm). +You can browse the [Nexus repository for `.rpm` packages](https://nexus.clever-cloud.com/#browse/browse:rpm). - Link to Nexus [yum-repositories docs](https://help.sonatype.com/en/yum-repositories.html) The repository is not signed, but the `.rpm` packages are. -The repo description is maintained in this git repo at `templates/rpm/cc-nexus-rpm.repo`. It's published on the Cellar at [https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo](https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo). The public key is published on the Cellar at [https://clever-tools.clever-cloud.com/gpg/cc-nexus-rpm.public.gpg.key](https://clever-tools.clever-cloud.com/gpg/cc-nexus-rpm.public.gpg.key). The private key, public key and passphrase are stored in our vault. +You can download the repository configuration on the Cellar at [https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo](https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo). The public key is published on the Cellar at [https://clever-tools.clever-cloud.com/gpg/cc-nexus-rpm.public.gpg.key](https://clever-tools.clever-cloud.com/gpg/cc-nexus-rpm.public.gpg.key). The private key, public key and passphrase are stored in the maintainer vault. ### GnuPG Keys @@ -52,10 +52,10 @@ Steps to follow to generate a new pair of GnuPG keys: - Export the private key in a file - `gpg --armor --output cc-nexus-deb.private.gpg.key --export-secret-key ` - Update the private key where it's needed - - The `deb` private key and passphrase need to be set in both `deb` and `deb-stable` repo in Nexus. + - The `deb` private key and passphrase need to be set in both `deb` and `deb-stable` repositories in Nexus. - The `rpm` private key and passphrase need to be set in Jenkins. - Combine both keys into one file - - `cat cc-nexus-deb.*.gpg.key cc-nexus-deb.combined.gpg.key` + - `cat cc-nexus-deb.public.gpg.key cc-nexus-deb.private.gpg.key > cc-nexus-deb.combined.gpg.key` - Add the combined key to the vault along with the random passphrase. This is an example for `deb` but the same goes for `rpm`. From 8ec569024e15c1bb6853b09e4a0c88c667c2087d Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:08:25 +0200 Subject: [PATCH 11/25] manage(cli): align Kubernetes defaults, kubeconfig, version check and node group rules with the CLI --- content/doc/manage/cli/kubernetes.md | 40 ++++++++++++++++++---------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/content/doc/manage/cli/kubernetes.md b/content/doc/manage/cli/kubernetes.md index 02a8b3574..26ab5348b 100644 --- a/content/doc/manage/cli/kubernetes.md +++ b/content/doc/manage/cli/kubernetes.md @@ -23,7 +23,7 @@ aliases: - /doc/cli/kubernetes --- -Clever Tools 4.9+ exposes the full lifecycle of [Clever Kubernetes Engine](/doc/deploy/kubernetes/): cluster creation with detailed topology, ongoing operations, node group management, version upgrades and quota visibility. Once a cluster is `ACTIVE`, you drive it with `kubectl` like any other Kubernetes cluster. +Clever Tools 4.9+ exposes the full lifecycle of [Clever Kubernetes Engine](/doc/deploy/kubernetes/): cluster creation with detailed topology, ongoing operations, node group management, version upgrades, and quota visibility. Once a cluster is `ACTIVE`, you drive it with `kubectl` like any other Kubernetes cluster. - [Learn more about Kubernetes on Clever Cloud](/doc/deploy/kubernetes/) @@ -41,26 +41,26 @@ Check the command set is available: clever k8s ``` -In all examples below, target a specific organisation with the `--org` (or `-o`) option. Output format defaults to a human-readable table; pass `--format json` (or `-F json`) on read commands when you need structured output for scripts or pipelines. +Use `--org` (or `-o`) to target an organisation by ID or unambiguous name. Replace `platform-team` in the examples with your organisation name. Output format defaults to a human-readable table; pass `--format json` (or `-F json`) on read commands when you need structured output for scripts or pipelines. ## Create a cluster -The fastest way to create a cluster is to provide only a name. The platform picks `ALL_IN_ONE` as the default topology, the smallest available flavor (`S`) and a replication factor of `1`: +To create a cluster, provide a name. Clever Tools defaults to `ALL_IN_ONE` and selects the smallest flavor and minimum replication factor available for that topology: ```bash -clever k8s create myCluster --org +clever k8s create myCluster --org platform-team ``` Add `--watch` to follow the deployment until the cluster reaches `ACTIVE`: ```bash -clever k8s create myCluster --watch --org +clever k8s create myCluster --watch --org platform-team ``` -When you need a specific shape, combine topology, flavor, replication factor, version and an initial node group in a single command. Topology values (`all_in_one`, `dedicated_compute`, `distributed`) are accepted in lowercase or uppercase. The `--nodegroup :` option provisions an initial node group named `default`, ready to schedule workloads as soon as the cluster reaches `ACTIVE`. Use it on `dedicated_compute` and `distributed` clusters, which otherwise come up with no worker. `all_in_one` bundles already include an integrated worker on each bundle VM, so passing `--nodegroup` adds an *extra* pool — Clever Tools warns you and asks for confirmation in that case: +When you need a specific shape, combine topology, flavor, replication factor, version and an initial node group in a single command. Topology values (`all_in_one`, `dedicated_compute`, `distributed`) are accepted in lowercase or uppercase. The `--nodegroup :` option provisions an initial node group named `default`, ready to schedule workloads as soon as the cluster reaches `ACTIVE`. Use it on `dedicated_compute` and `distributed` clusters, which otherwise come up with no worker. `all_in_one` bundles already include an integrated worker on each bundle VM, so passing `--nodegroup` adds an *extra* pool; Clever Tools warns you and asks for confirmation in that case: ```bash -clever k8s create myCluster --org \ +clever k8s create myCluster --org platform-team \ --topology dedicated_compute --flavor S --replication-factor 3 \ --cluster-version 1.36 \ --description "Production cluster" \ @@ -70,9 +70,9 @@ clever k8s create myCluster --org \ --nodegroup M:3 ``` -The `--cluster-version` value is validated against the platform-supported versions before the API call; an unsupported value (e.g. `0.99`) is rejected upfront with the list of available versions. +The `--cluster-version` value is validated against the platform-supported versions before the API call: an unsupported value, for example `0.99`, fails with the list of available versions. -## List, get and inspect +## List, get, and inspect List the Kubernetes clusters of the active organisation: @@ -131,11 +131,13 @@ Persistent storage is a one-way toggle; once enabled, it cannot be removed from ## Get the kubeconfig file -Retrieve the kubeconfig of an `ACTIVE` cluster. Wait for the cluster to reach `ACTIVE` before redirecting the output to a file — the command is a no-op on non-ready clusters: +Retrieve the kubeconfig of an `ACTIVE` cluster. Wait for the cluster to reach `ACTIVE` before redirecting the output to a file. The command is a no-op on non-ready clusters: ```bash clever k8s get-kubeconfig myCluster -clever k8s get-kubeconfig myCluster > ~/.kube/config +mkdir -p ~/.kube +clever k8s get-kubeconfig myCluster > ~/.kube/mycluster.yaml +export KUBECONFIG="$HOME/.kube/mycluster.yaml" ``` Once the kubeconfig is in place, drive the cluster with `kubectl` as usual. With `--persistent-storage` enabled, the default `StorageClass` is provisioned automatically. `kubectl get nodes` lists the integrated workers immediately on `all_in_one` clusters; on `dedicated_compute` and `distributed` clusters, the list stays empty until you add a node group: @@ -159,11 +161,11 @@ clever k8s activity myCluster --limit 100 clever k8s activity myCluster -F json ``` -`quota` reports the Kubernetes quota, current usage and remaining capacity for the active organisation. Each organisation starts with **40 vCPU and 40 GB of RAM** during the public Beta: +`quota` reports the Kubernetes quota, current usage, and remaining capacity for your account. Add `--org` to inspect an organisation. Each organisation starts with **40 vCPU and 40 GB of RAM** across all its Kubernetes clusters by default, as detailed in [quotas and limits](/doc/deploy/kubernetes/#quotas-and-limits): ```bash clever k8s quota -clever k8s quota -F json +clever k8s quota --org platform-team -F json ``` ## Cluster version @@ -175,6 +177,12 @@ clever k8s version myCluster clever k8s version check myCluster ``` +Use JSON output to inspect versions without an interactive upgrade prompt: + +```bash +clever k8s version check myCluster -F json +``` + Drive the upgrade explicitly to a target version. The target is validated against the supported versions before the API call: ```bash @@ -191,6 +199,8 @@ clever k8s nodegroups create myCluster workers XS:3 --autoscaling --min 3 --max clever k8s nodegroups create myCluster workers XS:3 --description "GPU-intensive workers" --tag env:prod ``` +When creating a node group, `--autoscaling` requires both `--min` and `--max`. Supplying both bounds also enables autoscaling without `--autoscaling`. + Inspect node groups attached to a cluster: ```bash @@ -200,7 +210,7 @@ clever k8s nodegroups get myCluster workers clever k8s nodegroups get myCluster node_group_id ``` -Update bounds, target count, autoscaling state or metadata. Pass at least one of `--count`, `--min`, `--max`, `--autoscaling`, `--disable-autoscaling`, `--description` or `--tag`. Resizes are queued: the API rejects a second update while a previous resize is still running: +Update bounds, target count, autoscaling state, or metadata. Pass at least one of `--count`, `--min`, `--max`, `--autoscaling`, `--disable-autoscaling`, `--description` or `--tag`. Resizes are queued: the API rejects a second update while a previous resize is still running: ```bash clever k8s nodegroups update myCluster workers --count 5 @@ -209,6 +219,8 @@ clever k8s nodegroups update myCluster workers --disable-autoscaling clever k8s nodegroups update myCluster workers --description "Updated description" ``` +The `--autoscaling` and `--disable-autoscaling` flags are mutually exclusive. When supplying both bounds, `--min` must not exceed `--max`. + Delete a node group; nodes are drained and the underlying VMs are removed. Skip the confirmation prompt with `--yes`: ```bash From e6dd9205db0cf1cd60e381766d3799f9762c7b4b Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:08:25 +0200 Subject: [PATCH 12/25] manage(cli): fix the kv COMMAND example and document organisation targeting --- content/doc/manage/cli/kv-stores.md | 53 +++++++++++++++-------------- 1 file changed, 28 insertions(+), 25 deletions(-) diff --git a/content/doc/manage/cli/kv-stores.md b/content/doc/manage/cli/kv-stores.md index 12307900b..14771987a 100644 --- a/content/doc/manage/cli/kv-stores.md +++ b/content/doc/manage/cli/kv-stores.md @@ -16,49 +16,52 @@ aliases: - /doc/kv-stores --- -If you're using [Materia KV](/doc/deploy/databases/materia-kv/), our next generation of key-value databases, serverless, distributed, synchronously-replicated, compatible with the Redis® protocol (and later DynamoDB, GraphQL), you can easily create an add-on with Clever Tools: +You can use Clever Tools to send Redis protocol commands to [Materia KV](/doc/deploy/databases/materia-kv/) and Redis® add-ons. Create a Materia KV add-on, then enable the experimental `kv` command: -```console -clever addon create kv ADDON_NAME +```bash +clever addon create kv session-cache +clever features enable kv +clever kv session-cache PING +clever kv session-cache PING Hello ``` -And immediately use it with `clever kv` command: +The first `PING` returns `PONG`; the second returns `Hello`. Clever Tools connects using the add-on's `REDIS_URL` environment variable. You can identify the add-on by its name, add-on ID or real ID. Use an ID when several add-ons share the same name. + +To limit the lookup to an organisation, add `--org` (or `-o`): ```bash -clever features enable kv # KV command is in testing stage -clever kv ADDON_NAME_OR_ID PING # It will answer PONG -clever kv ADDON_NAME_OR_ID PING Hello # It will answer Hello +clever kv session-cache PING --org platform-team ``` -It helps you to inspect and interact with your Materia KV. Each is provided with environment variables about its host, port, and [Biscuit-based](https://biscuitsec.org) tokens, in multiple forms (to ensure compatibility with tools such those made for Redis®). - -> [!Tip] -> Clever KV command is also compatible with Redis® on Clever Cloud add-ons. - ## Commands -You can use `clever kv` to send any command supported by your add-on. Here are some examples: +You can send any Redis protocol command supported by your add-on. For example, store and retrieve a value, increment a counter, or set a key that expires after 120 seconds: ```bash -clever kv ADDON_NAME_OR_ID INCR myCounter # It will respond (integer) the incremented value -clever kv ADDON_NAME_OR_ID SET myKey myValue # It will respond OK -clever kv ADDON_NAME_OR_ID GET myKey # It will respond myValue -clever kv ADDON_NAME_OR_ID SET myKey myValue EX 120 # It will respond OK -clever kv ADDON_NAME_OR_ID TTL myKey # It will respond (integer) the remaining time to live of the key in seconds +clever kv session-cache SET session-status active +clever kv session-cache GET session-status +clever kv session-cache INCR session-count +clever kv session-cache SET session-status active EX 120 +clever kv session-cache TTL session-status ``` -> [!Tip] -> You can get a list of all supported commands with `clever kv ADDON_NAME_OR_ID COMMANDS` +Use `COMMAND` to inspect the commands supported by the add-on: -You can pass the result of JSON stringified values to tools like `jq` to query them, for example: +```bash +clever kv session-cache COMMAND +``` + +To query a stored JSON string with `jq`, pass the value directly to it: ```bash -clever kv ADDON_NAME_OR_ID SET myJsonFormatedKey '{"key": "value"}' -clever kv ADDON_NAME_OR_ID GET myJsonFormatedKey | jq .key +clever kv session-cache SET session-details '{"status": "active"}' +clever kv session-cache GET session-details | jq .status ``` -You can also use the `-F/--format` option to print a result in JSON format and query it with `jq`: +Use `--format json` (or `-F json`) to encode the command result as JSON. This is useful for responses containing arrays, such as `SCAN`: ```bash -clever kv ADDON_NAME_OR_ID scan 0 -F json | jq '.[1][0]' +clever kv session-cache SCAN 0 -F json | jq '.[1]' ``` + +`SCAN` returns a cursor and a batch of keys. Repeat it with the returned cursor until the cursor is `0` to complete the iteration. From 561ec31c6c10fac54300ce773f7c640e9634f54d Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:08:25 +0200 Subject: [PATCH 13/25] manage(cli): fix the Network Group member domain and get-config description --- content/doc/manage/cli/network-groups.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/content/doc/manage/cli/network-groups.md b/content/doc/manage/cli/network-groups.md index 13ddb8dc5..e4d1da48c 100644 --- a/content/doc/manage/cli/network-groups.md +++ b/content/doc/manage/cli/network-groups.md @@ -23,10 +23,9 @@ aliases: A Network Group is defined by an ID (`ngId`) and a `label`. It can be completed by a `description` and `tags`. -> [!NOTE] -> During testing phase, you can add add-ons and external peers to a Network Group, but these features are not yet fully supported. +During testing phase, you can add add-ons and external peers to a Network Group, but these features are not yet fully supported. -Tell us what you think of Network Groups and what features you need from it in [the dedicated section of our GitHub Community](https://github.com/CleverCloud/Community/discussions/categories/network-groups). +Share your feedback and feature requests in [the Network Groups section of the GitHub Community](https://github.com/CleverCloud/Community/discussions/categories/network-groups). - [Learn more about Network Groups](/doc/network/network-groups/) @@ -36,8 +35,7 @@ When you create a Network Group, a WireGuard configuration is generated with a c When an application connects to a Network Group, you can reach it on any port inside a NG through its domain name. Any instance of this application is a peer, you can reach independently through an IP (from the attributed CIDR). It works the same way for add-ons and external resources. -> [!TIP] -> A Network Group member domain name is composed this way: `.m.cc-ng.cloud` +A Network Group member domain name follows this pattern: `.m..cc-ng.cloud` ## Prerequisites @@ -57,7 +55,7 @@ In all the following examples, you can target a specific organisation with the ` ## Create a Network Group -A Network Group is simple to create: +Create a Network Group with a label: ```console clever ng create myNG @@ -111,7 +109,7 @@ clever ng unlink redis_xxx ngIdorLabel After an unlink, you may need to restart the application to apply the changes. -> [!TIP] +> [!TIP] Add-on IDs > To link add-ons to a Network Group, use real IDs (`mysql_xxx`, `postgresql_xxx`, `redis_xxx`, etc.). \ > Only add-ons deployed as of 2024 support Network Groups. If you can't access your add-on, migrate or restart it. @@ -151,13 +149,13 @@ clever ng search text_to_search -F json clever ng search text_to_search --type Member ``` -> [!NOTE] +> [!NOTE] Search and exact matches > The search command is case-insensitive and will return all resources containing the search string. > The get command looks for an exact match and will return an error if multiple resources are found. ## Get the WireGuard configuration of a Peer -To get the WireGuard configuration of a peer (a `json` formatted output is available): +To print the WireGuard configuration of an external peer, provide its ID or label and the Network Group: ```console clever ng get-config peerIdOrLabel myNG @@ -169,4 +167,4 @@ You can find ready to deploy projects using Network Groups in the following repo - -Create your own and [let us know](https://github.com/CleverCloud/Community/discussions/categories/network-groups)! +Share your projects in [the Network Groups discussion](https://github.com/CleverCloud/Community/discussions/categories/network-groups) From c21d0a6ba7b7e6f25eb3f98f9acbfd17cf5d1de9 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:08:25 +0200 Subject: [PATCH 14/25] manage(cli): document notification scopes and complete notify-email and webhooks examples --- .../doc/manage/cli/notifications-webhooks.md | 60 +++++++++---------- 1 file changed, 29 insertions(+), 31 deletions(-) diff --git a/content/doc/manage/cli/notifications-webhooks.md b/content/doc/manage/cli/notifications-webhooks.md index 3c8fb72cf..0786633c6 100644 --- a/content/doc/manage/cli/notifications-webhooks.md +++ b/content/doc/manage/cli/notifications-webhooks.md @@ -19,66 +19,64 @@ aliases: - /reference/clever-tools/notifications --- -When events happen on Clever Cloud, during add-ons or applications lifecycle for example, you can send email notifications or trigger webhooks. For each of the following command, you can list all items and/or target a specific user/organisation through these parameters: +You can send email notifications or trigger webhooks when [events occur](/doc/account-billing/notifications/#available-events) during an application or add-on lifecycle. -```console -[--org, -o, --owner] Organisation ID (or name, if unambiguous) -[--list-all] List all notifications for your user or for an organisation with the `--org` option (default: false) +By default, listing commands target the application linked to your current directory. Use `--list-all` to list notifications for your account, or `--org` (or `-o`) to target an organisation by ID or unambiguous name: + +```bash +clever notify-email --list-all +clever webhooks --org platform-team ``` ## notify-email -You can send email notifications when [an event occurs](/doc/account-billing/notifications/#available-events). To list them, use: +List email notifications in human or JSON format: -```console +```bash clever notify-email clever notify-email --format json ``` -To add a notification process to an application, use: +To create a notification for your linked application, provide a name and at least one recipient: -```console -clever notify-email add --notify ||"ORGANISATION" NAME +```bash +clever notify-email add deployment-alerts --notify operations@example.com ``` -Available options are: +The required `--notify` option accepts an email address, a user ID, or `ORGANISATION` to notify the whole organisation. Separate multiple recipients with commas. Use `--org` to create the notification in an organisation: -```console -[--event] TYPE Restrict notifications to specific event types -[--service] SERVICE_ID Restrict notifications to specific applications and add-ons ---notify ||"ORGANISATION" Notify a user, a specific email address or the whole organisation (multiple values allowed, comma separated) +```bash +clever notify-email add deployment-alerts --org platform-team --notify ORGANISATION ``` -To delete a notification process, use: +Use `--event` to restrict event types and `--service` to restrict applications or add-ons. Both accept comma-separated values. The `--service` option requires `--org`. + +To delete a notification, replace `notification_id` with an ID from the listing. Include `--org` when the notification belongs to an organisation: -```console -clever notify-email remove NOTIFICATION-ID +```bash +clever notify-email remove notification_id --org platform-team ``` ## webhooks -You can trigger Webhooks when an event occurs. To list them, use: +List webhooks in JSON format: -```console +```bash clever webhooks -F json ``` -To add a webhook to an application, use: +To create a webhook for your linked application, provide a name and your receiving endpoint URL. Replace the URL below with your endpoint: -```console -clever webhooks add NAME URL +```bash +clever webhooks add deployment-alerts https://hooks.example.com/deployments ``` -You can set the format, restrict to a service or [event types](/doc/account-billing/notifications/#available-events) through these parameters: +For `webhooks add`, `--format` selects the request body format: `raw` (the default), `flowdock`, `gitter`, or `slack`. On the listing command, `--format` instead selects `human` or `json` output. -```console -[--format] FORMAT Format of the body sent to the webhook ('raw', 'slack', 'gitter', or 'flowdock') (default: raw) -[--event] TYPE Restrict notifications to specific event types -[--service] SERVICE_ID Restrict notifications to specific applications and add-ons -``` +Use `--event` to restrict event types and `--service` to restrict applications or add-ons. Both accept comma-separated values. The `--service` option requires `--org`. Without `--service`, specifying `--org` creates a webhook for the organisation without restricting it to your linked application. -To delete a webhook, use: +To delete a webhook, replace `notification_id` with an ID from the listing: -```console -clever webhooks remove NOTIFICATION-ID +```bash +clever webhooks remove notification_id --org platform-team ``` From 24cf64e94fdd6df1eb9f9b61d879ecf6c11fc098 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:08:25 +0200 Subject: [PATCH 15/25] manage(cli): add the Otoroshi Swagger UI and clarify operator version updates --- content/doc/manage/cli/operators.md | 37 +++++++++++++++++------------ 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/content/doc/manage/cli/operators.md b/content/doc/manage/cli/operators.md index e25a41b68..c58a920ac 100644 --- a/content/doc/manage/cli/operators.md +++ b/content/doc/manage/cli/operators.md @@ -21,7 +21,7 @@ Operators allow you to deploy services as turnkey solutions on Clever Cloud. The clever features enable operators ``` -Then, you can use the commands to manage Keycloak, Matomo, Metabase and Otoroshi instances on Clever Cloud. For example to list them deployed services: +Then, you can use the commands to manage Keycloak, Matomo, Metabase and Otoroshi instances on Clever Cloud. To list deployed services: ```console clever keycloak @@ -37,9 +37,8 @@ clever keycloak get myKeycloak clever matomo get matomo_id --format json ``` -> [!TIP] -> You can target a deployed service by its ID or name. -> +You can target a deployed service by its ID or name. + ## Service management To restart or rebuild (restart without cache) a deployed service, use: @@ -62,22 +61,30 @@ clever otoroshi open logs myOtoroshi clever otoroshi open webui otoroshi_id ``` +To open the Otoroshi Swagger UI, use: + +```bash +clever otoroshi open swaggerui myOtoroshi +``` + ## Version management -To check the version of a deployed service, use: +Keycloak, Metabase and Otoroshi support version management. To check the version of a deployed service, use: ```console -clever matomo version check matomo_id +clever otoroshi version check otoroshi_id clever metabase version check myMetabase --format json ``` -To update to a specific version, use: +In the human output format, version checks can offer an interactive upgrade prompt. Use `--format json` to inspect versions without this prompt. + +To update to a specific available version, use: ```console clever keycloak version update myKeycloak --target 24.0.1 ``` -To see a list of available versions, don't provide a target version: +To select an available version interactively and update the service, omit `--target`: ```console clever otoroshi version update otoroshi_id @@ -85,28 +92,28 @@ clever otoroshi version update otoroshi_id ## Network Groups -Keycloak and Otoroshi can be easily linked to a [Network Group](/doc/manage/cli/network-groups/). To enable/disable this feature, use: +Keycloak and Otoroshi can be linked to a [Network Group](/doc/manage/cli/network-groups/). To enable/disable this feature, use: ```console clever keycloak enable-ng myKeycloak clever otoroshi disable-ng otoroshi_id ``` -> [!NOTE] +> [!NOTE] Keycloak clustering > On Clever Cloud Keycloak uses Network Groups for its secure cluster feature. When you enable it, the Keycloak application is automatically scaled to 2 instances and the cluster automatically configured. When you disable the Network Group feature, the application is scaled down to 1 instance and the cluster is removed. ## Otoroshictl -Otoroshi instances can be managed using the `otoroshictl` command line tool. Clever Tools provides an easy way to use it, by providing Otoroshi instances configuration in a compliant YAML format: +You can manage Otoroshi instances with `otoroshictl`. Clever Tools exports their configuration in a compatible YAML format. With Rust and Cargo installed, use: ```bash -# Install otoroshictl with Rust's Cargo and enable operators/otoroshi command in Clever Tools: +# Install otoroshictl and enable the operators feature cargo install otoroshictl clever features enable operators -clever otoroshi get-config | otoroshictl config import --current --stdin +clever otoroshi get-config myOtoroshi | otoroshictl config import --current --stdin otoroshictl resources get routes ``` -> [!TIP] -> You can add as many Otoroshi instances as you want to your `otoroshictl` configuration by repeating this command with different instance IDs or names. Just add the `--current` flag to the one you want to use by default. +> [!TIP] Multiple instances +> You can add as many Otoroshi instances as you want to your `otoroshictl` configuration by repeating this command with different instance IDs or names. Add the `--current` flag to the one you want to use by default. From 085df588fb1339ac04cbc73a18c6caa62d4a9b4a Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:08:26 +0200 Subject: [PATCH 16/25] manage(cli): show the active profile and JSON profile listing --- content/doc/manage/cli/profiles.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/content/doc/manage/cli/profiles.md b/content/doc/manage/cli/profiles.md index 38e900ebf..a79189446 100644 --- a/content/doc/manage/cli/profiles.md +++ b/content/doc/manage/cli/profiles.md @@ -16,11 +16,11 @@ aliases: You can use multiple profiles with Clever Tools, all stored in the configuration file. The active profile is the first one in the list and is used for all commands. Each profile contains your authentication data and an optional set of overrides for custom Clever Cloud deployments (API host, Console URL, etc.). -> [!TIP] +> [!TIP] Configuration file > The configuration file lives in your OS config directory: > -> - Windows: `%APPDATA%\clever-cloud\clever-tools.json` > - Other systems: XDG config directory (typically `~/.config/clever-cloud/clever-tools.json`) +> - Windows: `%APPDATA%\clever-cloud\clever-tools.json` ## Create and use multiple profiles @@ -35,6 +35,15 @@ List and inspect profiles (the active one is marked): ```bash clever profile list +clever profile list -F json +``` + +Inspect the active profile or open its account page in the Console: + +```bash +clever profile +clever profile -F json +clever profile open ``` Switch to another profile: From a3ec7d9b8412b684ae865d97e0fb9a45c41baf3a Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:08:26 +0200 Subject: [PATCH 17/25] manage(cli): replace published-config and service placeholders with complete examples --- .../doc/manage/cli/services-depedencies.md | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/content/doc/manage/cli/services-depedencies.md b/content/doc/manage/cli/services-depedencies.md index 02d9566c1..fa45a6853 100644 --- a/content/doc/manage/cli/services-depedencies.md +++ b/content/doc/manage/cli/services-depedencies.md @@ -14,7 +14,7 @@ aliases: - /doc/cli/services-depedencies --- -On Clever Cloud, applications can expose configuration to share environment variables with other services within the same account/organisation. 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. +On Clever Cloud, applications can expose configuration to share environment variables with other services within the same account/organisation. Add-ons expose their configuration by default. 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, adding `--app APP_ID_OR_NAME` or a local alias (`--alias`, `-a`). @@ -31,13 +31,21 @@ clever published-config --format shell To configure exposed configuration, use: ```console -clever published-config COMMAND +clever published-config set SERVICE_URL https://payments-api.cleverapps.io +clever published-config rm SERVICE_URL ``` -Available commands are `set`, `rm` (remove) or `import`. The latter reads data from `stdin` so use it as is: +Use `set` to add or update a variable, `rm` to remove one, and `import` to replace the entire published configuration from standard input. Create a file containing `NAME=value` entries before importing it: ```console -clever published-config import < file.config +printf '%s\n' 'SERVICE_URL=https://payments-api.cleverapps.io' > service.config +clever published-config import < service.config +``` + +For JSON input, add `--json`: + +```bash +printf '%s\n' '[{"name":"SERVICE_URL","value":"https://payments-api.cleverapps.io"}]' | clever published-config import --json ``` ## service @@ -49,26 +57,18 @@ clever service clever service --format json ``` -You can filter results through these options. +Use `--only-apps` or `--only-addons` to filter dependencies. These options are mutually exclusive. Add `--show-all` to include services available for linking: -```console -[--only-apps] Only show app dependencies (default: false) -[--only-addons] Only show add-on dependencies (default: false) -[--show-all] Show all available add-ons and applications (default: false) +```bash +clever service --only-apps +clever service --only-addons --show-all ``` -To create or delete services dependencies, use: +To add or remove a dependency, provide its ID or unambiguous name: -```console -clever service COMMAND ADDON_OR_APP_ID -clever service COMMAND ADDON_OR_APP_NAME -``` - -Available commands are: - -```console -link-app Add an existing app as a dependency -unlink-app Remove an app from the dependencies -link-addon Link an existing add-on to this application -unlink-addon Unlink an add-on from this application +```bash +clever service link-app payments-api +clever service unlink-app payments-api +clever service link-addon session-cache +clever service unlink-addon session-cache ``` From 5655bdfee1a53e95a9814b357a7a0fca1303c454 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:12:10 +0200 Subject: [PATCH 18/25] api: drop the obsolete tokens feature flag from the Clever Tools example --- content/api/_index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/api/_index.md b/content/api/_index.md index 3cef27815..2e9e87005 100644 --- a/content/api/_index.md +++ b/content/api/_index.md @@ -50,10 +50,9 @@ Clever Cloud Console allows you to easily create and manage API tokens. ![Manage API tokens in Clever Cloud Console](/images/console-api-tokens.webp) -[Clever Tools](https://github.com/CleverCloud/clever-tools) provides a `clever tokens` set of commands. This feature needs to be enabled: +[Clever Tools](https://github.com/CleverCloud/clever-tools) provides a `clever tokens` set of commands: ```bash -clever features enable tokens clever tokens create "CI job Foobar" clever tokens create "Quick local test" --expiration 1h ``` From 3b3b48dc363fdba5682984a0b88b12031e9520cd Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:12:10 +0200 Subject: [PATCH 19/25] tips-and-tricks: fix the ssh application option and the JSON output short option --- content/doc/tips-and-tricks.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/doc/tips-and-tricks.md b/content/doc/tips-and-tricks.md index 0d59f7166..a15a8cc46 100644 --- a/content/doc/tips-and-tricks.md +++ b/content/doc/tips-and-tricks.md @@ -166,9 +166,9 @@ Then run `clever login` to get started. While the platform uses immutable infrastructure, sometimes you need SSH access for debugging. Use these commands: ```bash -clever ssh # Connect to default app -clever ssh --app app_id_or_name # Connect to specific app -clever ssh -a app_id_or_name -i ~/.ssh/id_ed25519 # Use specific key +clever ssh # Connect to default app +clever ssh --app app_id_or_name # Connect to specific app +clever ssh --app app_id_or_name -i ~/.ssh/id_ed25519 # Use specific key ``` For extended debugging sessions, set `CC_TROUBLESHOOT=true` as an environment variable. This keeps your application running for up to 1 hour, even if errors occur. @@ -201,7 +201,7 @@ This command groups applications by organisation for easy reference. ### JSON Output Support -Add `--format json` or `-f json` to most commands for machine-readable output: +Add `--format json` or `-F json` to most commands for machine-readable output: ```bash clever applications list --format json From 9461c7f7debf32708b9ba4bbdc7ff45e0c309fa5 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:12:10 +0200 Subject: [PATCH 20/25] develop(access-logs): document TCP and SSH access logs and the transport column --- content/doc/develop/observability/access-logs.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/content/doc/develop/observability/access-logs.md b/content/doc/develop/observability/access-logs.md index 3b6f52608..0456d152d 100644 --- a/content/doc/develop/observability/access-logs.md +++ b/content/doc/develop/observability/access-logs.md @@ -3,7 +3,7 @@ type: docs weight: 10 linkTitle: Access Logs title: Access Logs -description: Read the HTTP requests reaching your applications on Clever Cloud, with their status, latency and origin +description: Read the HTTP requests, TCP redirections and SSH connections reaching your applications on Clever Cloud, with their status, latency and origin keywords: - access logs - http requests @@ -16,9 +16,9 @@ aliases: - /doc/observability/access-logs --- -Access logs contain all incoming HTTP requests to your application. For the output of the application itself, see [Logs](/doc/develop/observability/logs). +Access logs contain all incoming HTTP requests to your application, along with TCP redirections and SSH connections to its instances. For the output of the application itself, see [Logs](/doc/develop/observability/logs). -It contains all incoming HTTP requests to your application. You can see access logs with the following command: +You can see access logs with the following command: ```bash clever accesslogs @@ -29,13 +29,13 @@ If you don't specify any options, the logs display continuously. To change the output, specify the `--format` (`-F`) flag with one of these values: -- `human` (default): a human-readable, colored table +- `human` (default): a human-readable, colored table. The second column shows the transport of each line, `HTTP`, `TCP` or `SSH`. Status, method and path columns only appear for HTTP requests. ```txt - 2026-06-24T08:05:43.880Z 255.255.255.255 FR/Nantes 200 GET / + 2026-06-24T08:05:43.880Z HTTP 255.255.255.255 FR/Nantes 200 GET / ``` -- `clf`: [Common Log Format](https://en.wikipedia.org/wiki/Common_Log_Format) +- `clf`: [Common Log Format](https://en.wikipedia.org/wiki/Common_Log_Format), which only outputs HTTP access logs ```txt 255.255.255.255 - - [24/Jun/2026:08:05:43 +0000] "GET /" 200 562 @@ -89,3 +89,5 @@ To change the output, specify the `--format` (`-F`) flag with one of these value "tls": null } ``` + + TCP redirections and SSH connections use the same shape, without the `http` section. From 19c03a5151eefe9911ae170033369c7ab52a3cf4 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:13:10 +0200 Subject: [PATCH 21/25] deploy(operators): pass the target version with --target in Metabase and Otoroshi examples --- content/doc/deploy/services/metabase.md | 6 +++--- content/doc/deploy/services/otoroshi.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content/doc/deploy/services/metabase.md b/content/doc/deploy/services/metabase.md index 01b5dddc1..5ee40ec92 100644 --- a/content/doc/deploy/services/metabase.md +++ b/content/doc/deploy/services/metabase.md @@ -176,7 +176,7 @@ Of course, you have full control other this. The Java application of your Metaba ```bash # Set a specific supported version at creation -clever addon create metabase --addon-version myMetabase +clever addon create metabase --addon-version VERSION myMetabase # Enable Operators commands clever features enable operators @@ -185,9 +185,9 @@ clever features enable operators clever metabase version check metabase_name_or_id clever metabase version check metabase_name_or_id --format json -# Update to a specific supported version +# Update to a supported version, picked interactively or set with --target clever metabase version update myMetabase -clever metabase version update myMetabase +clever metabase version update myMetabase --target VERSION ``` - Learn more about [Operators commands in Clever Tools](/doc/manage/cli/operators/) diff --git a/content/doc/deploy/services/otoroshi.md b/content/doc/deploy/services/otoroshi.md index b8fbe8359..4b3134d80 100644 --- a/content/doc/deploy/services/otoroshi.md +++ b/content/doc/deploy/services/otoroshi.md @@ -83,7 +83,7 @@ To change the version of an Otoroshi add-on on Clever Cloud, you can use the `CC ```bash # Set a specific supported version at creation # You can add options to set base or routes domains if needed -clever addon create otoroshi myOtoroshi --addon-version +clever addon create otoroshi myOtoroshi --addon-version VERSION # Enable Operators commands clever features enable operators @@ -92,9 +92,9 @@ clever features enable operators clever otoroshi version check otoroshi_name_or_id clever otoroshi version check otoroshi_name_or_id --format json -# Update to a specific supported version +# Update to a supported version, picked interactively or set with --target clever otoroshi version update myOtoroshi -clever otoroshi version update myOtoroshi +clever otoroshi version update myOtoroshi --target VERSION ``` - Learn more about [Operators commands in Clever Tools](/doc/manage/cli/operators/) From a30c84cd64300c1ccbabdabbcd07eec17951e24d Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:14:12 +0200 Subject: [PATCH 22/25] develop(logs): accept add-on real IDs and durations in logs examples --- content/doc/develop/observability/logs.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/doc/develop/observability/logs.md b/content/doc/develop/observability/logs.md index e1d1b3ed6..fffe42994 100644 --- a/content/doc/develop/observability/logs.md +++ b/content/doc/develop/observability/logs.md @@ -42,17 +42,17 @@ Log management is also available through [Clever Tools](https://github.com/Cleve clever logs ``` -You can add `--since`, followed by a duration or a date (ISO8601 format). The `--until` flag should be followed by a date (ISO8601 format). +You can add `--since` or `--until`, followed by a duration, a number of seconds or a date (ISO8601 format). ```bash clever logs --since 2h clever logs --until 2024-04-15T13:37:42Z ``` -You can also get your add-on's logs by using `--addon` flag, the value must be the add-on ID starting by `addon_`. +You can also get your add-on's logs by using `--addon` flag, the value is the add-on ID starting by `addon_`, or its real ID: ```bash -clever logs --addon +clever logs --addon postgresql_xxxxxxxx ``` {{< callout type="warning" >}} From 1e71322cdd55db05b6fe059b49a66429eb9b71e4 Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:14:12 +0200 Subject: [PATCH 23/25] find-help(faq): replace the database backups synopsis with a runnable command --- content/doc/find-help/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/doc/find-help/faq.md b/content/doc/find-help/faq.md index 2d76deed7..6d4de5150 100644 --- a/content/doc/find-help/faq.md +++ b/content/doc/find-help/faq.md @@ -265,7 +265,7 @@ If a VACUUM operation needs more disk that there is remaining, migrating to the Clever Cloud stores all backups on [Cellar](https://www.clever.cloud/product/cellar-object-storage/), a replicated object storage service with three copies distributed across datacenters in the PAR region to ensure durability. Even if one datacenter fails, your backups remain safe. -For custom configurations (for example, multiple retention policies), contact Support. To locate backups not visible in the Console, use [Clever Tools](https://github.com/CleverCloud/clever-tools) with: `clever database backups DATABASE-ID [--format, -F] FORMAT`. Find more [documentation on restoring backups with the CLI](/doc/manage/cli/addons/#database-backups). +For custom configurations (for example, multiple retention policies), contact Support. To locate backups not visible in the Console, use [Clever Tools](https://github.com/CleverCloud/clever-tools) with: `clever database backups DATABASE_ID --format json`. Find more [documentation on restoring backups with the CLI](/doc/manage/cli/addons/#database-backups). {{% /details %}} {{% details title="I can't create my add-on" closed="true" %}} From 6fbadb18f911c57e65985da1116b07ba2258d99a Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:44:15 +0200 Subject: [PATCH 24/25] manage(cli): mark option lists as text instead of console commands --- content/doc/manage/cli/_index.md | 2 +- content/doc/manage/cli/addons.md | 4 ++-- content/doc/manage/cli/applications/_index.md | 10 +++++----- content/doc/manage/cli/applications/configuration.md | 4 ++-- .../manage/cli/applications/deployment-lifecycle.md | 10 +++++----- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/content/doc/manage/cli/_index.md b/content/doc/manage/cli/_index.md index b518d9dfa..c46d2df41 100644 --- a/content/doc/manage/cli/_index.md +++ b/content/doc/manage/cli/_index.md @@ -72,7 +72,7 @@ clever help For each of them, you can add these parameters: -```console +```text [--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) diff --git a/content/doc/manage/cli/addons.md b/content/doc/manage/cli/addons.md index c1c4c33cf..99bfbd8dd 100644 --- a/content/doc/manage/cli/addons.md +++ b/content/doc/manage/cli/addons.md @@ -17,7 +17,7 @@ aliases: Add-ons on Clever Cloud are databases, storage services, tools or third party services you can enable through `clever addon providers`. For each of the following commands, you can target a specific user/organisation: -```console +```text [--org, -o, --owner] Organisation ID (or name, if unambiguous) ``` @@ -61,7 +61,7 @@ When you set `--org`, Clever Tools checks that the requested region is available You can set `plan`, `region`, `version`, `option` and directly `link` an add-on to an application through these parameters: -```console +```text [--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 diff --git a/content/doc/manage/cli/applications/_index.md b/content/doc/manage/cli/applications/_index.md index 6fec39fe6..e2ecc2239 100644 --- a/content/doc/manage/cli/applications/_index.md +++ b/content/doc/manage/cli/applications/_index.md @@ -35,7 +35,7 @@ You can also use one of the following optional parameters: ### Tasks -```console +```text [--task, -T] COMMAND ``` @@ -48,7 +48,7 @@ You can execute a Task whenever needed through a `clever restart` or modify it a #### GitHub repositories -```console +```text --github owner/repo ``` @@ -58,7 +58,7 @@ If your Clever Cloud account is linked to a GitHub account, you can deploy any o You can ask to deploy your application in a specific organisation/user account, region, with an alias different from its name: -```console +```text [--org, -o, --owner] ID/NAME [--alias, -a] ALIAS [--region, -r] ZONE @@ -85,7 +85,7 @@ Default region is our Paris datacenters (`par`), but it can be: After the application creation, you can ask for a `json` formatted report instead of an `human` sentence: -```console +```text [--format, -F] FORMAT ``` @@ -119,7 +119,7 @@ clever applications If you only need to get aliases or the result in the JSON format: -```console +```text [--only-aliases] List only application aliases (default: false) [--json, -j] Show result in JSON format (default: false) ``` diff --git a/content/doc/manage/cli/applications/configuration.md b/content/doc/manage/cli/applications/configuration.md index 8dab479c5..a1bcbbe40 100644 --- a/content/doc/manage/cli/applications/configuration.md +++ b/content/doc/manage/cli/applications/configuration.md @@ -40,7 +40,7 @@ clever config update FLAGS Available parameters are : -```console +```text [--name] Set name [--description] Set description [--enable-zero-downtime] Enable zero-downtime (default: false) @@ -146,7 +146,7 @@ clever domain diag --filter mydomain.tld 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: -```console +```text [--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 diff --git a/content/doc/manage/cli/applications/deployment-lifecycle.md b/content/doc/manage/cli/applications/deployment-lifecycle.md index 792792836..1e4592f51 100644 --- a/content/doc/manage/cli/applications/deployment-lifecycle.md +++ b/content/doc/manage/cli/applications/deployment-lifecycle.md @@ -35,7 +35,7 @@ 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: -```console +```text [--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) @@ -83,7 +83,7 @@ clever restart By default, it will use its build cache when available. But you can override it or use other available options: -```console +```text [--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) @@ -131,7 +131,7 @@ clever logs You can also get logs from a specific timeline, deployment or add-on through options: -```console +```text [--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 date, positive number in seconds or duration, e.g.: 1h) [--search] SEARCH Fetch logs matching this pattern @@ -153,7 +153,7 @@ clever accesslogs You can also get access logs from a specific timeline through options, in multiple formats: -```console +```text [--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 date, positive number in seconds or duration, e.g.: 1h) [--format, -F] FORMAT Output format (human, json, json-stream, clf) (default: human) @@ -188,7 +188,7 @@ clever activity By default, it will show you last 10 deployments. You can show all or listen to a stream of incoming deployments through options: -```console +```text [--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) From f59fadf6aab2ac3ff2339928e10fad9c73ac7d6c Mon Sep 17 00:00:00 2001 From: David Legrand Date: Fri, 11 Sep 2026 15:20:11 +0200 Subject: [PATCH 25/25] changelog: Clever Tools 5.0 --- .../changelog/2026/09-11-clever-tools-5.0.md | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 content/changelog/2026/09-11-clever-tools-5.0.md diff --git a/content/changelog/2026/09-11-clever-tools-5.0.md b/content/changelog/2026/09-11-clever-tools-5.0.md new file mode 100644 index 000000000..9ebea10b5 --- /dev/null +++ b/content/changelog/2026/09-11-clever-tools-5.0.md @@ -0,0 +1,73 @@ +--- +title: "Clever Tools 5.0: Node.js 24, system Git by default and Splunk drains" +date: 2026-09-11 +description: Clever Tools 5.0 moves to Node.js 24, deploys with your system Git by default, forwards logs to Splunk, displays TCP and SSH access logs and honors proxy settings +tags: + - clever-tools + - cli +authors: + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +excludeSearch: true +--- + +[Clever Tools 5.0.0](https://github.com/CleverCloud/clever-tools/releases/tag/5.0.0) is available. It's a new major version: the npm package now requires Node.js 24, and Git operations rely on the `git` installed on your system by default. This release also forwards logs to Splunk, displays TCP and SSH access logs, and honors proxy environment variables. + +## Node.js 24 + +Clever Tools now runs on Node.js 24, the current Active LTS. If you install the package with npm, pnpm or Yarn, upgrade Node.js to version 24 or later first. Standalone binaries embed their own Node.js runtime, so this change doesn't affect them. + +## System Git by default + +Clever Tools used a pure JavaScript Git implementation to deploy your applications. It only supports HTTP, slows down on repositories with rewritten history, times out on large pushes and can't deploy from a linked worktree. The `system-git` feature, which uses the `git` available in your `PATH` instead, is now stable and enabled by default. + +If `git` isn't installed on your system, or if you face an issue with this backend, fall back to the previous implementation: + +```bash +clever features disable system-git +``` + +In the latter case, [open an issue on the Clever Tools repository](https://github.com/CleverCloud/clever-tools/issues) with the command you ran and its output, so the team can fix it. + +## Splunk drains and per-type drain commands + +You can now forward logs of an application or an add-on to a [Splunk HTTP Event Collector](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector) (HEC). The `--index` and `--sourcetype` options are optional: without them, the values bound to your HEC token apply. As self-hosted Splunk instances ship a self-signed certificate on port `8088` by default, add `--tls-verification trustful` if you didn't replace it: + +```bash +clever drain create splunk https://splunk.example.com:8088/services/collector/event --hec-token "$SPLUNK_HEC_TOKEN" +clever drain create splunk https://splunk.example.com:8088/services/collector/event --hec-token "$SPLUNK_HEC_TOKEN" --tls-verification trustful +``` + +`clever drain create` now exposes one subcommand per drain type. Valid commands keep the same syntax, but the help of each type only lists the options it supports, and a wrong option fails before any API call instead of being silently ignored. + +## TCP and SSH access logs + +`clever accesslogs` used to skip every access log without an HTTP section. It now displays TCP redirections and SSH connections too, with their transport in a new column. HTTP methods and paths also get their own columns, so paths stay aligned whatever the method length. The CLF output format remains dedicated to HTTP access logs. + +## Proxy support + +Clever Tools now honors the `http_proxy` and `https_proxy` environment variables, like `curl` or `kubectl` do, and `no_proxy` to exclude hosts. When none of them is set, requests go out directly as before: + +```bash +export https_proxy="http://proxy.internal:3128" +clever status +``` + +## Other changes + +`clever ssh` no longer falls back to password authentication, so a missing or unregistered key fails immediately, and its `--identity-file` option now presents the requested key. When `clever login` can't open a browser, for example on a headless Linux system, it prints a warning instead of crashing and waits for you to open the displayed URL. + +Clever Tools now notifies you when a new version is available, even in standalone binaries. On Arch Linux, Clever Cloud now maintains the [`clever-tools`](https://aur.archlinux.org/packages/clever-tools/) AUR package, which installs the npm package, alongside [`clever-tools-bin`](https://aur.archlinux.org/packages/clever-tools-bin/) and its standalone binary. + +## How to upgrade + +To upgrade Clever Tools, follow the [new update guide](/doc/manage/cli/install/update/) for the installation method you use. For example with `npm`, once Node.js 24 is installed: + +```bash +npm install -g clever-tools +clever version +```