clever-tools 5.0.2 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clever-tools",
-  "version": "5.0.2",
+  "version": "5.1.0",
   "description": "Command Line Interface for Clever Cloud.",
   "keywords": [
     "cli",

package/src/commands/README.md

@@ -36,6 +36,7 @@ These options are available for all commands:
 |[`clever env`](./env/env.docs.md)|Manage environment variables of an application|
 |[`clever features`](./features/features.docs.md)|Manage Clever Tools experimental features|
 |[`clever help`](./help/help.docs.md)|Display help about the Clever Cloud CLI|
+|[`clever instances`](./instances/instances.docs.md)|List instances of an application|
 |[`clever k8s`](./k8s/k8s.docs.md)|Manage Kubernetes clusters|
 |[`clever keycloak`](./keycloak/keycloak.docs.md)|Manage Clever Cloud Keycloak services|
 |[`clever kv`](./kv/kv.docs.md)|Send a raw command to a Materia KV or Redis® add-on|

package/src/commands/drain/drain.command.js

@@ -48,6 +48,7 @@ export const drainCommand = defineCommand({
         const formattedDrains = drains.map((drain) => {
           return {
             ID: drain.id,
+            Kind: drain.kind,
             Status: drain.status.status,
             'Execution status': drain.execution.status,
             URL: drain.recipient.url,

package/src/commands/drain/drain.create.betterstack.command.js

@@ -6,6 +6,7 @@ import { Logger } from '../../logger.js';
 import { createLogDrain, resolveDrainResource } from '../../models/drain.js';
 import { addonIdOrRealIdOption, aliasOption, appIdOrNameOption } from '../global.options.js';
 import { drainUrlArg } from './drain.args.js';
+import { drainKindOption } from './drain.options.js';
 
 export const drainCreateBetterstackCommand = defineCommand({
   description: 'Create a Better Stack drain',
@@ -18,16 +19,17 @@ export const drainCreateBetterstackCommand = defineCommand({
       aliases: ['t'],
       placeholder: 'source-token',
     }),
+    kind: drainKindOption,
     alias: aliasOption,
     appIdOrName: appIdOrNameOption,
     addonIdOrRealId: addonIdOrRealIdOption,
   },
   args: [drainUrlArg],
   async handler(options, url) {
-    const { alias, appIdOrName, addonIdOrRealId, sourceToken } = options;
+    const { kind, alias, appIdOrName, addonIdOrRealId, sourceToken } = options;
     const { ownerId, resourceId } = await resolveDrainResource(alias, appIdOrName, addonIdOrRealId);
 
-    const drain = await createLogDrain('BETTERSTACK', ownerId, resourceId, url, { sourceToken });
+    const drain = await createLogDrain('BETTERSTACK', kind, ownerId, resourceId, url, { sourceToken });
 
     Logger.printSuccess(
       `Better Stack drain ${styleText(['bold', 'green'], drain.id)} has been successfully created and enabled!`,

package/src/commands/drain/drain.create.datadog.command.js

@@ -4,21 +4,23 @@ import { Logger } from '../../logger.js';
 import { createLogDrain, resolveDrainResource } from '../../models/drain.js';
 import { addonIdOrRealIdOption, aliasOption, appIdOrNameOption } from '../global.options.js';
 import { drainUrlArg } from './drain.args.js';
+import { drainKindOption } from './drain.options.js';
 
 export const drainCreateDatadogCommand = defineCommand({
   description: 'Create a Datadog drain',
   since: '0.9.0',
   options: {
+    kind: drainKindOption,
     alias: aliasOption,
     appIdOrName: appIdOrNameOption,
     addonIdOrRealId: addonIdOrRealIdOption,
   },
   args: [drainUrlArg],
   async handler(options, url) {
-    const { alias, appIdOrName, addonIdOrRealId } = options;
+    const { kind, alias, appIdOrName, addonIdOrRealId } = options;
     const { ownerId, resourceId } = await resolveDrainResource(alias, appIdOrName, addonIdOrRealId);
 
-    const drain = await createLogDrain('DATADOG', ownerId, resourceId, url);
+    const drain = await createLogDrain('DATADOG', kind, ownerId, resourceId, url);
 
     Logger.printSuccess(
       `Datadog drain ${styleText(['bold', 'green'], drain.id)} has been successfully created and enabled!`,

package/src/commands/drain/drain.create.elasticsearch.command.js

@@ -6,7 +6,7 @@ import { styleText } from '../../lib/style-text.js';
 import { Logger } from '../../logger.js';
 import { createLogDrain, resolveDrainResource } from '../../models/drain.js';
 import { addonIdOrRealIdOption, aliasOption, appIdOrNameOption } from '../global.options.js';
-import { drainPasswordOption, drainUsernameOption } from './drain.options.js';
+import { drainKindOption, drainPasswordOption, drainUsernameOption } from './drain.options.js';
 
 export const drainCreateElasticsearchCommand = defineCommand({
   description: 'Create an Elasticsearch drain',
@@ -21,6 +21,7 @@ export const drainCreateElasticsearchCommand = defineCommand({
     }),
     username: drainUsernameOption,
     password: drainPasswordOption,
+    kind: drainKindOption,
     alias: aliasOption,
     appIdOrName: appIdOrNameOption,
     addonIdOrRealId: addonIdOrRealIdOption,
@@ -36,10 +37,10 @@ export const drainCreateElasticsearchCommand = defineCommand({
     }),
   ],
   async handler(options, url) {
-    const { alias, appIdOrName, addonIdOrRealId, index, username, password } = options;
+    const { kind, alias, appIdOrName, addonIdOrRealId, index, username, password } = options;
     const { ownerId, resourceId } = await resolveDrainResource(alias, appIdOrName, addonIdOrRealId);
 
-    const drain = await createLogDrain('ELASTICSEARCH', ownerId, resourceId, url, { index, username, password });
+    const drain = await createLogDrain('ELASTICSEARCH', kind, ownerId, resourceId, url, { index, username, password });
 
     Logger.printSuccess(
       `Elasticsearch drain ${styleText(['bold', 'green'], drain.id)} has been successfully created and enabled!`,

package/src/commands/drain/drain.create.newrelic.command.js

@@ -6,6 +6,7 @@ import { Logger } from '../../logger.js';
 import { createLogDrain, resolveDrainResource } from '../../models/drain.js';
 import { addonIdOrRealIdOption, aliasOption, appIdOrNameOption } from '../global.options.js';
 import { drainUrlArg } from './drain.args.js';
+import { drainKindOption } from './drain.options.js';
 
 export const drainCreateNewRelicCommand = defineCommand({
   description: 'Create a New Relic drain',
@@ -18,16 +19,17 @@ export const drainCreateNewRelicCommand = defineCommand({
       aliases: ['k'],
       placeholder: 'api-key',
     }),
+    kind: drainKindOption,
     alias: aliasOption,
     appIdOrName: appIdOrNameOption,
     addonIdOrRealId: addonIdOrRealIdOption,
   },
   args: [drainUrlArg],
   async handler(options, url) {
-    const { alias, appIdOrName, addonIdOrRealId, apiKey } = options;
+    const { kind, alias, appIdOrName, addonIdOrRealId, apiKey } = options;
     const { ownerId, resourceId } = await resolveDrainResource(alias, appIdOrName, addonIdOrRealId);
 
-    const drain = await createLogDrain('NEWRELIC', ownerId, resourceId, url, { apiKey });
+    const drain = await createLogDrain('NEWRELIC', kind, ownerId, resourceId, url, { apiKey });
 
     Logger.printSuccess(
       `New Relic drain ${styleText(['bold', 'green'], drain.id)} has been successfully created and enabled!`,

package/src/commands/drain/drain.create.ovh-tcp.command.js

@@ -4,23 +4,24 @@ import { Logger } from '../../logger.js';
 import { createLogDrain, resolveDrainResource } from '../../models/drain.js';
 import { addonIdOrRealIdOption, aliasOption, appIdOrNameOption } from '../global.options.js';
 import { drainUrlArg } from './drain.args.js';
-import { drainSdParamsOption } from './drain.options.js';
+import { drainKindOption, drainSdParamsOption } from './drain.options.js';
 
 export const drainCreateOvhTcpCommand = defineCommand({
   description: 'Create an OVH TCP drain',
   since: '0.9.0',
   options: {
     rfc5424StructuredDataParameters: drainSdParamsOption,
+    kind: drainKindOption,
     alias: aliasOption,
     appIdOrName: appIdOrNameOption,
     addonIdOrRealId: addonIdOrRealIdOption,
   },
   args: [drainUrlArg],
   async handler(options, url) {
-    const { alias, appIdOrName, addonIdOrRealId, rfc5424StructuredDataParameters } = options;
+    const { kind, alias, appIdOrName, addonIdOrRealId, rfc5424StructuredDataParameters } = options;
     const { ownerId, resourceId } = await resolveDrainResource(alias, appIdOrName, addonIdOrRealId);
 
-    const drain = await createLogDrain('OVH_TCP', ownerId, resourceId, url, { rfc5424StructuredDataParameters });
+    const drain = await createLogDrain('OVH_TCP', kind, ownerId, resourceId, url, { rfc5424StructuredDataParameters });
 
     Logger.printSuccess(
       `OVH TCP drain ${styleText(['bold', 'green'], drain.id)} has been successfully created and enabled!`,

package/src/commands/drain/drain.create.raw-http.command.js

@@ -4,7 +4,7 @@ import { Logger } from '../../logger.js';
 import { createLogDrain, resolveDrainResource } from '../../models/drain.js';
 import { addonIdOrRealIdOption, aliasOption, appIdOrNameOption } from '../global.options.js';
 import { drainUrlArg } from './drain.args.js';
-import { drainPasswordOption, drainUsernameOption } from './drain.options.js';
+import { drainKindOption, drainPasswordOption, drainUsernameOption } from './drain.options.js';
 
 export const drainCreateRawHttpCommand = defineCommand({
   description: 'Create a raw HTTP drain',
@@ -12,16 +12,17 @@ export const drainCreateRawHttpCommand = defineCommand({
   options: {
     username: drainUsernameOption,
     password: drainPasswordOption,
+    kind: drainKindOption,
     alias: aliasOption,
     appIdOrName: appIdOrNameOption,
     addonIdOrRealId: addonIdOrRealIdOption,
   },
   args: [drainUrlArg],
   async handler(options, url) {
-    const { alias, appIdOrName, addonIdOrRealId, username, password } = options;
+    const { kind, alias, appIdOrName, addonIdOrRealId, username, password } = options;
     const { ownerId, resourceId } = await resolveDrainResource(alias, appIdOrName, addonIdOrRealId);
 
-    const drain = await createLogDrain('RAW_HTTP', ownerId, resourceId, url, { username, password });
+    const drain = await createLogDrain('RAW_HTTP', kind, ownerId, resourceId, url, { username, password });
 
     Logger.printSuccess(
       `Raw HTTP drain ${styleText(['bold', 'green'], drain.id)} has been successfully created and enabled!`,

package/src/commands/drain/drain.create.splunk.command.js

@@ -6,6 +6,7 @@ import { Logger } from '../../logger.js';
 import { createLogDrain, resolveDrainResource } from '../../models/drain.js';
 import { addonIdOrRealIdOption, aliasOption, appIdOrNameOption } from '../global.options.js';
 import { drainUrlArg } from './drain.args.js';
+import { drainKindOption } from './drain.options.js';
 
 export const drainCreateSplunkCommand = defineCommand({
   description: 'Create a Splunk HEC drain',
@@ -38,16 +39,17 @@ export const drainCreateSplunkCommand = defineCommand({
       description: 'TLS verification mode, use `trustful` to accept a self-signed certificate',
       placeholder: 'tls-verification',
     }),
+    kind: drainKindOption,
     alias: aliasOption,
     appIdOrName: appIdOrNameOption,
     addonIdOrRealId: addonIdOrRealIdOption,
   },
   args: [drainUrlArg],
   async handler(options, url) {
-    const { alias, appIdOrName, addonIdOrRealId, token, index, sourcetype, tlsVerification } = options;
+    const { kind, alias, appIdOrName, addonIdOrRealId, token, index, sourcetype, tlsVerification } = options;
     const { ownerId, resourceId } = await resolveDrainResource(alias, appIdOrName, addonIdOrRealId);
 
-    const drain = await createLogDrain('SPLUNK', ownerId, resourceId, url, {
+    const drain = await createLogDrain('SPLUNK', kind, ownerId, resourceId, url, {
       token,
       index,
       sourcetype,

package/src/commands/drain/drain.create.syslog-tcp.command.js

@@ -4,23 +4,26 @@ import { Logger } from '../../logger.js';
 import { createLogDrain, resolveDrainResource } from '../../models/drain.js';
 import { addonIdOrRealIdOption, aliasOption, appIdOrNameOption } from '../global.options.js';
 import { drainUrlArg } from './drain.args.js';
-import { drainSdParamsOption } from './drain.options.js';
+import { drainKindOption, drainSdParamsOption } from './drain.options.js';
 
 export const drainCreateSyslogTcpCommand = defineCommand({
   description: 'Create a Syslog TCP drain',
   since: '0.9.0',
   options: {
     rfc5424StructuredDataParameters: drainSdParamsOption,
+    kind: drainKindOption,
     alias: aliasOption,
     appIdOrName: appIdOrNameOption,
     addonIdOrRealId: addonIdOrRealIdOption,
   },
   args: [drainUrlArg],
   async handler(options, url) {
-    const { alias, appIdOrName, addonIdOrRealId, rfc5424StructuredDataParameters } = options;
+    const { kind, alias, appIdOrName, addonIdOrRealId, rfc5424StructuredDataParameters } = options;
     const { ownerId, resourceId } = await resolveDrainResource(alias, appIdOrName, addonIdOrRealId);
 
-    const drain = await createLogDrain('SYSLOG_TCP', ownerId, resourceId, url, { rfc5424StructuredDataParameters });
+    const drain = await createLogDrain('SYSLOG_TCP', kind, ownerId, resourceId, url, {
+      rfc5424StructuredDataParameters,
+    });
 
     Logger.printSuccess(
       `Syslog TCP drain ${styleText(['bold', 'green'], drain.id)} has been successfully created and enabled!`,

package/src/commands/drain/drain.create.syslog-udp.command.js

@@ -4,23 +4,26 @@ import { Logger } from '../../logger.js';
 import { createLogDrain, resolveDrainResource } from '../../models/drain.js';
 import { addonIdOrRealIdOption, aliasOption, appIdOrNameOption } from '../global.options.js';
 import { drainUrlArg } from './drain.args.js';
-import { drainSdParamsOption } from './drain.options.js';
+import { drainKindOption, drainSdParamsOption } from './drain.options.js';
 
 export const drainCreateSyslogUdpCommand = defineCommand({
   description: 'Create a Syslog UDP drain',
   since: '0.9.0',
   options: {
     rfc5424StructuredDataParameters: drainSdParamsOption,
+    kind: drainKindOption,
     alias: aliasOption,
     appIdOrName: appIdOrNameOption,
     addonIdOrRealId: addonIdOrRealIdOption,
   },
   args: [drainUrlArg],
   async handler(options, url) {
-    const { alias, appIdOrName, addonIdOrRealId, rfc5424StructuredDataParameters } = options;
+    const { kind, alias, appIdOrName, addonIdOrRealId, rfc5424StructuredDataParameters } = options;
     const { ownerId, resourceId } = await resolveDrainResource(alias, appIdOrName, addonIdOrRealId);
 
-    const drain = await createLogDrain('SYSLOG_UDP', ownerId, resourceId, url, { rfc5424StructuredDataParameters });
+    const drain = await createLogDrain('SYSLOG_UDP', kind, ownerId, resourceId, url, {
+      rfc5424StructuredDataParameters,
+    });
 
     Logger.printSuccess(
       `Syslog UDP drain ${styleText(['bold', 'green'], drain.id)} has been successfully created and enabled!`,

package/src/commands/drain/drain.docs.md

@@ -70,6 +70,7 @@ clever drain create betterstack --source-token <source-token> <drain-url> [optio
 |`--addon` `<addon-id>`|Add-on ID or real ID|
 |`-a`, `--alias` `<alias>`|Short name for the application|
 |`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`--kind` `<kind>`|Kind of logs sent to the drain (LOG, ACCESSLOG) (default: LOG)|
 
 ### Examples
 
@@ -100,6 +101,7 @@ clever drain create datadog <drain-url> [options]
 |`--addon` `<addon-id>`|Add-on ID or real ID|
 |`-a`, `--alias` `<alias>`|Short name for the application|
 |`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`--kind` `<kind>`|Kind of logs sent to the drain (LOG, ACCESSLOG) (default: LOG)|
 
 ### Examples
 
@@ -136,6 +138,7 @@ clever drain create elasticsearch --index-prefix <index-prefix> <drain-url> [opt
 |`--addon` `<addon-id>`|Add-on ID or real ID|
 |`-a`, `--alias` `<alias>`|Short name for the application|
 |`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`--kind` `<kind>`|Kind of logs sent to the drain (LOG, ACCESSLOG) (default: LOG)|
 |`-p`, `--password` `<password>`|Basic auth password|
 |`-u`, `--username` `<username>`|Basic auth username|
 
@@ -171,6 +174,7 @@ clever drain create newrelic --api-key <api-key> <drain-url> [options]
 |`--addon` `<addon-id>`|Add-on ID or real ID|
 |`-a`, `--alias` `<alias>`|Short name for the application|
 |`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`--kind` `<kind>`|Kind of logs sent to the drain (LOG, ACCESSLOG) (default: LOG)|
 
 ### Examples
 
@@ -201,6 +205,7 @@ clever drain create ovh-tcp <drain-url> [options]
 |`--addon` `<addon-id>`|Add-on ID or real ID|
 |`-a`, `--alias` `<alias>`|Short name for the application|
 |`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`--kind` `<kind>`|Kind of logs sent to the drain (LOG, ACCESSLOG) (default: LOG)|
 |`-s`, `--sd-params` `<sd-params>`|RFC5424 structured data parameters, e.g.: `token=\"REDACTED\"`|
 
 ### Examples
@@ -232,6 +237,7 @@ clever drain create raw-http <drain-url> [options]
 |`--addon` `<addon-id>`|Add-on ID or real ID|
 |`-a`, `--alias` `<alias>`|Short name for the application|
 |`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`--kind` `<kind>`|Kind of logs sent to the drain (LOG, ACCESSLOG) (default: LOG)|
 |`-p`, `--password` `<password>`|Basic auth password|
 |`-u`, `--username` `<username>`|Basic auth username|
 
@@ -267,6 +273,7 @@ clever drain create splunk --hec-token <hec-token> <drain-url> [options]
 |`-a`, `--alias` `<alias>`|Short name for the application|
 |`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
 |`--index` `<index>`|Optional target index, the HEC token's own index is used if not set|
+|`--kind` `<kind>`|Kind of logs sent to the drain (LOG, ACCESSLOG) (default: LOG)|
 |`--sourcetype` `<sourcetype>`|Optional sourcetype, the HEC token's own sourcetype is used if not set|
 |`--tls-verification` `<tls-verification>`|TLS verification mode, use `trustful` to accept a self-signed certificate (default, trustful)|
 
@@ -291,6 +298,7 @@ clever drain create syslog-tcp <drain-url> [options]
 |`--addon` `<addon-id>`|Add-on ID or real ID|
 |`-a`, `--alias` `<alias>`|Short name for the application|
 |`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`--kind` `<kind>`|Kind of logs sent to the drain (LOG, ACCESSLOG) (default: LOG)|
 |`-s`, `--sd-params` `<sd-params>`|RFC5424 structured data parameters, e.g.: `token=\"REDACTED\"`|
 
 ### Examples
@@ -323,6 +331,7 @@ clever drain create syslog-udp <drain-url> [options]
 |`--addon` `<addon-id>`|Add-on ID or real ID|
 |`-a`, `--alias` `<alias>`|Short name for the application|
 |`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`--kind` `<kind>`|Kind of logs sent to the drain (LOG, ACCESSLOG) (default: LOG)|
 |`-s`, `--sd-params` `<sd-params>`|RFC5424 structured data parameters, e.g.: `token=\"REDACTED\"`|
 
 ### Examples

package/src/commands/drain/drain.options.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { defineOption } from '../../lib/define-option.js';
+import { DRAIN_KINDS } from '../../models/drain.js';
 
 export const drainUsernameOption = defineOption({
   name: 'username',
@@ -24,3 +25,10 @@ export const drainSdParamsOption = defineOption({
   aliases: ['s'],
   placeholder: 'sd-params',
 });
+
+export const drainKindOption = defineOption({
+  name: 'kind',
+  schema: z.enum(DRAIN_KINDS).default('LOG'),
+  description: 'Kind of logs sent to the drain',
+  placeholder: 'kind',
+});

package/src/commands/global.commands.js

@@ -72,6 +72,7 @@ import { featuresEnableCommand } from './features/features.enable.command.js';
 import { featuresInfoCommand } from './features/features.info.command.js';
 import { featuresListCommand } from './features/features.list.command.js';
 import { helpCommand } from './help/help.command.js';
+import { instancesCommand } from './instances/instances.command.js';
 import { k8sActivityCommand } from './k8s/k8s.activity.command.js';
 import { k8sAddPersistentStorageCommand } from './k8s/k8s.add-persistent-storage.command.js';
 import { k8sCommand } from './k8s/k8s.command.js';
@@ -328,6 +329,7 @@ export const globalCommands = {
     },
   ],
   help: helpCommand,
+  instances: instancesCommand,
   k8s: [
     k8sCommand,
     {

package/src/commands/instances/instances.command.js

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { formatTable } from '../../format-table.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { defineOption } from '../../lib/define-option.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import * as Application from '../../models/application.js';
+import { listInstances } from '../../models/instances.js';
+import { date } from '../../parsers.js';
+import { aliasOption, appIdOrNameOption, humanJsonOutputFormatOption } from '../global.options.js';
+
+export const instancesCommand = defineCommand({
+  description: 'List instances of an application',
+  since: '5.1.0',
+  options: {
+    all: defineOption({
+      name: 'all',
+      schema: z.boolean().default(false),
+      description: 'List instances in any state, including deleted ones (default: only running instances)',
+    }),
+    since: defineOption({
+      name: 'after',
+      schema: z.string().transform(date).optional(),
+      description:
+        'List instances that existed after this date/time, in any state (ISO8601 date, positive number in seconds or duration, e.g.: 1h)',
+      aliases: ['since'],
+      placeholder: 'after',
+    }),
+    until: defineOption({
+      name: 'before',
+      schema: z.string().transform(date).optional(),
+      description:
+        'List instances that existed before this date/time, in any state (ISO8601 date, positive number in seconds or duration, e.g.: 1h)',
+      aliases: ['until'],
+      placeholder: 'before',
+    }),
+    deploymentId: defineOption({
+      name: 'deployment-id',
+      schema: z.string().optional(),
+      description: 'List instances created by this deployment, in any state',
+      placeholder: 'deployment-id',
+    }),
+    limit: defineOption({
+      name: 'limit',
+      schema: z.coerce.number().int().min(1).max(1000).default(100),
+      description: 'Maximum number of instances to list, keeping the most recent ones (1 to 1000)',
+      placeholder: 'limit',
+    }),
+    alias: aliasOption,
+    app: appIdOrNameOption,
+    format: humanJsonOutputFormatOption,
+  },
+  async handler(options) {
+    const { alias, app: appIdOrName, all, since, until, deploymentId, limit, format } = options;
+    if (since != null && until != null && since > until) {
+      throw new Error('--after must be earlier than or equal to --before');
+    }
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+
+    // Date and deployment filters also include past instances
+    const hasFilters = since != null || until != null || deploymentId != null;
+    const onlyRunning = !all && !hasFilters;
+
+    const instances = await listInstances({
+      ownerId,
+      appId,
+      onlyRunning,
+      since,
+      until,
+      deploymentId,
+      limit,
+    });
+
+    switch (format) {
+      case 'json': {
+        Logger.printJson(instances);
+        break;
+      }
+      case 'human':
+      default: {
+        if (instances.length === 0) {
+          Logger.println(
+            styleText(
+              'blue',
+              onlyRunning
+                ? 'No running instances found for this application'
+                : hasFilters
+                  ? 'No instances found matching the filters'
+                  : 'No instances found for this application',
+            ),
+          );
+          return;
+        }
+
+        const headers = ['CREATED', 'STATE', '#', 'FLAVOR', 'INSTANCE ID', 'DEPLOYMENT ID'];
+        const rows = instances.map((instance) => [
+          `${instance.createdAt.substring(0, 19).replace('T', ' ')}Z`,
+          instance.state,
+          instance.isBuildVm ? 'build' : String(instance.instanceNumber ?? '?'),
+          instance.flavor ?? '',
+          instance.id,
+          instance.deploymentId,
+        ]);
+        Logger.println(formatTable([headers, ...rows]));
+      }
+    }
+  },
+});

package/src/commands/instances/instances.docs.md

@@ -0,0 +1,22 @@
+# 📖 `clever instances` command reference
+
+## ➡️ `clever instances` <kbd>Since 5.1.0</kbd>
+
+List instances of an application
+
+```bash
+clever instances [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`--after`, `--since` `<after>`|List instances that existed after this date/time, in any state (ISO8601 date, positive number in seconds or duration, e.g.: 1h)|
+|`-a`, `--alias` `<alias>`|Short name for the application|
+|`--all`|List instances in any state, including deleted ones (default: only running instances)|
+|`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`--before`, `--until` `<before>`|List instances that existed before this date/time, in any state (ISO8601 date, positive number in seconds or duration, e.g.: 1h)|
+|`--deployment-id` `<deployment-id>`|List instances created by this deployment, in any state|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+|`--limit` `<limit>`|Maximum number of instances to list, keeping the most recent ones (1 to 1000) (default: 100)|

package/src/commands/kv/kv.command.js

@@ -1,6 +1,7 @@
 import { getAllEnvVars } from '@clevercloud/client/esm/api/v2/addon.js';
 import Redis from 'ioredis';
 import { z } from 'zod';
+import { ambiguousNameError } from '../../lib/ambiguous-name-error.js';
 import { defineArgument } from '../../lib/define-argument.js';
 import { defineCommand } from '../../lib/define-command.js';
 import { styleText } from '../../lib/style-text.js';
@@ -70,10 +71,12 @@ export const kvCommand = defineCommand({
     }
 
     if (addons.length > 1) {
-      const formattedAddons = addons
-        .map(({ addonId, ownerId }) => `\n${styleText('grey', `- ${addonId} (${ownerId})`)}`)
-        .join('');
-      throw new Error(`Several add-ons found for '${addonIdOrRealIdOrName}', use ID instead:${formattedAddons}`);
+      const candidates = addons.map(({ name, addonId, ownerId }) => ({
+        name,
+        id: addonId,
+        details: `owner ${ownerId}`,
+      }));
+      throw ambiguousNameError(addonIdOrRealIdOrName, candidates);
     }
 
     const { addonId, ownerId } = addons[0];

package/src/commands/ssh/ssh.command.js

@@ -1,4 +1,3 @@
-import { getAllInstances } from '@clevercloud/client/esm/api/v2/application.js';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
@@ -6,10 +5,13 @@ import { config } from '../../config/config.js';
 import { defineCommand } from '../../lib/define-command.js';
 import { defineOption } from '../../lib/define-option.js';
 import { selectAnswer } from '../../lib/prompts.js';
+import { styleText } from '../../lib/style-text.js';
 import * as Application from '../../models/application.js';
-import { sendToApi } from '../../models/send-to-api.js';
+import { listInstances } from '../../models/instances.js';
 import { aliasOption, appIdOrNameOption } from '../global.options.js';
 
+/** @typedef {import('../../models/instances.js').Instance} Instance */
+
 export const sshCommand = defineCommand({
   description: 'Connect to running instances through SSH',
   since: '0.7.0',
@@ -28,33 +30,62 @@ export const sshCommand = defineCommand({
       aliases: ['c'],
       placeholder: 'command',
     }),
+    instance: defineOption({
+      name: 'instance',
+      // Most specific first: z.union keeps the first match and an ID accepts any string
+      schema: z
+        .union([z.literal('any'), z.string().regex(/^\d+$/).transform(Number).pipe(z.int()), z.string().min(1)])
+        .optional(),
+      description:
+        'Instance to connect to, by ID or number, or `any` (skips interactive selection). Build VMs are only picked by ID, or by `any` when no other instance is running',
+      placeholder: 'instance-id|number|any',
+    }),
     alias: aliasOption,
     app: appIdOrNameOption,
   },
   args: [],
   async handler(options) {
-    const { alias, app: appIdOrName, identityFile, command } = options;
+    const { alias, app: appIdOrName, identityFile, command, instance } = options;
     const { appId, ownerId } = await Application.resolveId(appIdOrName, alias);
 
-    const instances = await getAllInstances({ id: ownerId, appId }).then(sendToApi);
+    const instances = await listInstances({ ownerId, appId, onlyRunning: true });
 
     if (instances.length === 0) {
       throw new Error('No running instances found for this application');
     }
 
+    // Build VMs also carry number 0, keep them last
+    // Instances have no number at the very beginning of booting
+    // Numbers restart at 0 on each deployment, instances sharing a number are ordered newest first
+    const sortedInstances = instances.toSorted((a, b) => {
+      return (
+        Number(a.isBuildVm) - Number(b.isBuildVm) ||
+        (a.instanceNumber ?? Infinity) - (b.instanceNumber ?? Infinity) ||
+        b.createdAt.localeCompare(a.createdAt)
+      );
+    });
+
+    if (instance == null && sortedInstances.length > 1 && !process.stdin.isTTY) {
+      throw new Error(`Multiple instances are running, pick one with --instance:\n${formatInstances(sortedInstances)}`);
+    }
+
     let sshTarget;
-    if (instances.length === 1) {
-      sshTarget = instances[0].id;
-    } else if (process.stdin.isTTY) {
-      const choices = instances
-        .sort((a, b) => a.instanceNumber - b.instanceNumber)
-        .map((inst) => ({
-          name: `${inst.displayName} - Instance ${inst.instanceNumber} - ${inst.state} (${inst.id})`,
-          value: inst.id,
-        }));
-      sshTarget = await selectAnswer('Select an instance:', choices);
+    if (instance != null) {
+      const selectedInstance = selectInstance(sortedInstances, instance);
+      if (selectedInstance == null) {
+        throw new Error(
+          `No instance ${styleText('red', String(instance))} on this application, pick one with --instance:\n${formatInstances(sortedInstances)}`,
+        );
+      }
+      sshTarget = selectedInstance.id;
+    } else if (sortedInstances.length === 1) {
+      sshTarget = sortedInstances[0].id;
     } else {
-      throw new Error('Multiple instances are running. Cannot select in non-interactive mode.');
+      const choices = sortedInstances.map((i) => ({
+        name: `${i.name ?? '?'} - ${i.isBuildVm ? 'Build instance' : `Instance ${i.instanceNumber ?? '?'}`} - ${i.state} (${i.id})`,
+        value: i.id,
+      }));
+      sshTarget = await selectAnswer('Select an instance:', choices);
     }
 
     const sshParams = [];
@@ -126,3 +157,45 @@ export const sshCommand = defineCommand({
     process.exit(exitCode);
   },
 });
+
+/**
+ * Pick the instance the caller asked for, by ID, by number, or `any`, or nothing when none match.
+ *
+ * Numbers are not unique: while a deployment rolls, the instance going away and the one coming up
+ * carry the same number. `UP` ones are preferred among them, the most recent first, and `any` prefers
+ * an `UP` one over the lowest number. Build VMs are also numbered 0, so a number never picks them,
+ * and `any` only falls back to them when no other instance is running.
+ *
+ * @param {Array<Instance>} sortedInstances - build VMs last, then sorted by instance number, most recent first
+ * @param {string | number | 'any'} wanted - an instance ID, an instance number or `any`
+ * @returns {Instance | null}
+ */
+function selectInstance(sortedInstances, wanted) {
+  const runtimeInstances = sortedInstances.filter((i) => !i.isBuildVm);
+  if (wanted === 'any') {
+    return getReadiestInstance(runtimeInstances) ?? getReadiestInstance(sortedInstances);
+  }
+  if (typeof wanted === 'number') {
+    return getReadiestInstance(runtimeInstances.filter((i) => i.instanceNumber === wanted));
+  }
+  return sortedInstances.find((i) => i.id === wanted) ?? null;
+}
+
+/**
+ * The first serving instance, or the first one when none is serving.
+ * @param {Array<Instance>} sortedInstances - sorted by instance number, then most recent first
+ * @returns {Instance | null}
+ */
+function getReadiestInstance(sortedInstances) {
+  return sortedInstances.find((i) => i.state === 'UP') ?? sortedInstances[0] ?? null;
+}
+
+/**
+ * One line per instance, to help the caller pick one with `--instance`.
+ * @param {Array<Instance>} instances
+ * @returns {string}
+ */
+function formatInstances(instances) {
+  const lines = instances.map((i) => `  - ${i.isBuildVm ? 'build' : (i.instanceNumber ?? '?')} ${i.id} (${i.state})`);
+  return styleText('grey', lines.join('\n'));
+}

package/src/commands/ssh/ssh.docs.md

@@ -16,3 +16,13 @@ clever ssh [options]
 |`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
 |`-c`, `--command` `<command>`|Execute a command on the remote instance and exit|
 |`-i`, `--identity-file` `<identity-file>`|SSH identity file|
+|`--instance` `<instance-id\|number\|any>`|Instance to connect to, by ID or number, or `any` (skips interactive selection). Build VMs are only picked by ID, or by `any` when no other instance is running|
+
+### Examples
+
+```bash
+clever ssh --instance 0 -c hostname     # instance number 0
+clever ssh --instance any -c hostname   # any running instance, a build VM only if nothing else runs
+clever instances                        # during a deployment, the build VM shows as `build`
+clever ssh --instance <build-vm-id>     # connect to a build VM
+```

package/src/lib/ambiguous-name-error.js

@@ -0,0 +1,15 @@
+import { styleText } from './style-text.js';
+
+/**
+ * Builds the error thrown when a name matches several resources, listing them so the user can pick one by ID
+ * @param {string} name - The name that matched several resources
+ * @param {Array<{ name: string, id: string, details?: string }>} candidates - The resources matching the name, with optional details to tell them apart
+ * @param {string} [idLabel] - How the identifier to use instead is called (e.g. "real ID", "key")
+ * @returns {Error}
+ */
+export function ambiguousNameError(name, candidates, idLabel = 'ID') {
+  const list = candidates
+    .map((c) => `  - ${c.name} ${styleText('grey', `(${[c.id, c.details].filter(Boolean).join(', ')})`)}`)
+    .join('\n');
+  return new Error(`Ambiguous name ${styleText('red', name)}, use the ${idLabel} instead:\n${list}`);
+}

package/src/lib/k8s.js

@@ -1,4 +1,5 @@
 import dedent from 'dedent';
+import { ambiguousNameError } from './ambiguous-name-error.js';
 import { ask, confirm, selectAnswer } from './prompts.js';
 import { styleText } from './style-text.js';
 
@@ -244,10 +245,7 @@ export async function getClusterIdFromAddonIdOrName(addonIdOrName, ownerId) {
       throw new Error(`No Kubernetes cluster found with the name ${styleText('red', name)}`);
     }
     if (matches.length > 1) {
-      const listing = matches.map((c) => `- ${c.name} (${c.id})`).join('\n');
-      throw new Error(
-        `Multiple Kubernetes clusters found with the name ${styleText('red', name)}, use the ID instead:\n${styleText('grey', listing)}`,
-      );
+      throw ambiguousNameError(name, matches);
     }
     return matches[0].id;
   } else {
@@ -436,10 +434,7 @@ async function resolveNodeGroupId(ownerId, clusterId, nodeGroupIdOrName) {
     throw new Error(`No node group found with name ${styleText('red', nodeGroupIdOrName)}`);
   }
   if (matches.length > 1) {
-    const listing = matches.map((ng) => `- ${ng.name} (${ng.id})`).join('\n');
-    throw new Error(
-      `Multiple node groups found with the name ${styleText('red', nodeGroupIdOrName)}, use the ID instead:\n${styleText('grey', listing)}`,
-    );
+    throw ambiguousNameError(nodeGroupIdOrName, matches);
   }
   return matches[0].id;
 }

package/src/models/drain.js

@@ -17,16 +17,19 @@ export async function resolveDrainResource(alias, appIdOrName, addonIdOrRealId)
   return { ownerId, resourceId: appId };
 }
 
+export const DRAIN_KINDS = /** @type {const} */ (['LOG', 'ACCESSLOG']);
+
 /**
- * Creates a log drain, the recipient options that are not set are left out of the payload.
+ * Creates a drain, the recipient options that are not set are left out of the payload.
  * @param {string} type - Drain type, as expected by the API
+ * @param {typeof DRAIN_KINDS[number]} kind - Kind of logs sent to the drain
  * @param {string} ownerId
  * @param {string} resourceId
  * @param {string} url - Drain URL
  * @param {Record<string, unknown>} [recipientOptions] - Extra recipient fields, `null` and `undefined` ones are ignored
  */
-export function createLogDrain(type, ownerId, resourceId, url, recipientOptions = {}) {
-  const body = { kind: 'LOG', recipient: { type, url } };
+export function createLogDrain(type, kind, ownerId, resourceId, url, recipientOptions = {}) {
+  const body = { kind, recipient: { type, url } };
 
   for (const key in recipientOptions) {
     if (recipientOptions[key] != null) {
@@ -72,6 +75,7 @@ function formatThroughput(bytesPerSecond) {
 export function formatDrain(rawDrain) {
   const drainDetails = [
     ['ID', rawDrain.id],
+    ['Kind', rawDrain.kind],
     ['Status', rawDrain.status.status],
     ['Execution status', rawDrain.execution.status],
     ['URL', rawDrain.recipient.url],

package/src/models/instances.js

@@ -0,0 +1,75 @@
+import { getAllApplicationInstances } from '@clevercloud/client/esm/api/v4/instance.js';
+import { toDate } from '../lib/date-utils.js';
+import { sendToApi } from './send-to-api.js';
+
+// States in which the VM is running
+const RUNNING_STATES = [
+  'BOOTING',
+  'STARTING',
+  'READY',
+  'BUILDING',
+  'DEPLOYING',
+  'UP',
+  'TASK_IN_PROGRESS',
+  'MIGRATION_IN_PROGRESS',
+  'STOPPING',
+];
+
+/**
+ * @typedef {object} Instance
+ * @property {number} [instanceNumber] - Position of the instance within its deployment, starting at 0 (build VMs are also numbered 0), missing at the very beginning of booting
+ * @property {string} id
+ * @property {string|null} name
+ * @property {string} state
+ * @property {string|null} flavor
+ * @property {boolean} isBuildVm
+ * @property {string} deploymentId
+ * @property {string} createdAt - ISO 8601 date
+ * @property {string|null} deletedAt - ISO 8601 date
+ */
+
+/**
+ * Lists the instances of an application, sorted by creation date (oldest first).
+ * The API returns the most recent instances first, so `limit` keeps the N most recent ones.
+ * @param {object} params
+ * @param {string} params.ownerId
+ * @param {string} params.appId
+ * @param {boolean} [params.onlyRunning] - Only keep instances whose VM is running
+ * @param {Date} [params.since] - Only keep instances deleted at or after this date, or not deleted yet
+ * @param {Date} [params.until] - Only keep instances created at or before this date
+ * @param {string} [params.deploymentId] - Only keep instances created by this deployment
+ * @param {number} [params.limit]
+ * @returns {Promise<Array<Instance>>}
+ */
+export async function listInstances({ ownerId, appId, onlyRunning, since, until, deploymentId, limit }) {
+  const rawInstances = await getAllApplicationInstances({
+    ownerId,
+    applicationId: appId,
+    // The API rejects a repeated query parameter but accepts a comma-separated list
+    includeState: onlyRunning ? RUNNING_STATES.join(',') : undefined,
+    since: since?.toISOString(),
+    until: until?.toISOString(),
+    deploymentId,
+    limit,
+  }).then(sendToApi);
+
+  return rawInstances.map(normalizeInstance).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+
+/**
+ * @param {object} rawInstance - Instance as returned by the v4 orchestration API
+ * @returns {Instance}
+ */
+function normalizeInstance(rawInstance) {
+  return {
+    instanceNumber: rawInstance.index,
+    id: rawInstance.id,
+    name: rawInstance.name ?? null,
+    state: rawInstance.state,
+    flavor: rawInstance.flavor ?? null,
+    isBuildVm: rawInstance.isBuildVm,
+    deploymentId: rawInstance.deploymentId,
+    createdAt: toDate(rawInstance.creationDate).toISOString(),
+    deletedAt: toDate(rawInstance.deletionDate)?.toISOString() ?? null,
+  };
+}

package/src/models/ng.js

@@ -7,6 +7,7 @@ import {
 } from '@clevercloud/client/esm/api/v4/network-group.js';
 import crypto from 'node:crypto';
 import { searchNetworkGroupOrResource } from '../clever-client/ng.js';
+import { ambiguousNameError } from '../lib/ambiguous-name-error.js';
 import { styleText } from '../lib/style-text.js';
 import { Logger } from '../logger.js';
 import { getOwnerIdFromOrgIdOrName } from './ids-resolver.js';
@@ -189,8 +190,8 @@ export async function searchNgOrResource(idOrLabel, orgaIdOrName, type = 'all',
   }
 
   if (filtered.length > 1 && type !== 'all') {
-    throw new Error(`Multiple resources found for ${styleText('red', query)}, use ID instead:
-${filtered.map((f) => ` • ${f.id} ${styleText('grey', `(${f.domainName || f.label} - ${f.type})`)}`).join('\n')}`);
+    const candidates = filtered.map((f) => ({ name: f.domainName || f.label, id: f.id, details: f.type }));
+    throw ambiguousNameError(query, candidates);
   }
 
   // Deduplicate results

package/src/models/oauth-consumer.js

@@ -1,5 +1,6 @@
 import { get as getOauthConsumer } from '@clevercloud/client/esm/api/v2/oauth-consumer.js';
 import { getSummary } from '@clevercloud/client/esm/api/v2/user.js';
+import { ambiguousNameError } from '../lib/ambiguous-name-error.js';
 import { promptCheckbox } from '../lib/prompts.js';
 import { styleText } from '../lib/style-text.js';
 import { findOauthConsumersByKeyOrName } from './ids-resolver.js';
@@ -67,8 +68,8 @@ export async function resolveOauthConsumer(keyOrName) {
   }
 
   if (candidates.length > 1) {
-    const list = candidates.map((c) => `  - ${c.name} ${styleText('grey', `(${c.key})`)}`).join('\n');
-    throw new Error(`Ambiguous name ${styleText('red', keyOrName)}, use the key instead:\n${list}`);
+    const consumers = candidates.map((c) => ({ name: c.name, id: c.key }));
+    throw ambiguousNameError(keyOrName, consumers, 'key');
   }
 
   const { ownerId, key } = candidates[0];

package/src/models/operator.js

@@ -1,5 +1,5 @@
-import dedent from 'dedent';
 import { getOperator } from '../clever-client/operators.js';
+import { ambiguousNameError } from '../lib/ambiguous-name-error.js';
 import { styleText } from '../lib/style-text.js';
 import { findAddonsByNameOrId } from './ids-resolver.js';
 import { sendToApi } from './send-to-api.js';
@@ -36,10 +36,8 @@ export async function getSingleRealId(operatorIdOrName) {
   }
 
   if (operators.length > 1) {
-    throw new Error(dedent`
-      Ambiguous name ${styleText('red', name)}, use the real ID instead:
-        ${styleText('grey', operators.map((otoroshi) => `- ${otoroshi.name} (${otoroshi.realId})`).join('\n'))}
-    `);
+    const candidates = operators.map((o) => ({ name: o.name, id: o.realId }));
+    throw ambiguousNameError(name, candidates, 'real ID');
   }
 
   return operators[0].realId;

package/src/parsers.js

@@ -138,11 +138,10 @@ export function durationInSeconds(durationStr = '') {
   try {
     return parseSimpleDuration(durationStr);
   } catch {
-    const n = Number.parseInt(durationStr);
-    if (isNaN(n) || n < 0) {
+    if (!/^\d+$/.test(durationStr)) {
       throw new Error(errorMessage);
     }
-    return n;
+    return Number(durationStr);
   }
 }
 
@@ -165,6 +164,7 @@ function parseSimpleDuration(durationStr) {
     const d = ISO8601.parse(isoDuration);
     return ISO8601.toSeconds(d);
   }
+  throw new Error(`Unknown duration unit in "${durationStr}"`);
 }
 
 // Network Groups parsers