clever-tools 3.2.0 → 3.5.0

package/README.md

@@ -88,10 +88,10 @@ Where `type` is one of:
 Where region is one of:
 
 - `par` (Paris, [Clever Cloud](https://www.clever-cloud.com/infrastructure/))
+- `grahds` (Gravelines, HDS servers, OVHcloud)
 - `rbx` (Roubaix, OVHcloud)
 - `rbxhds` (Roubaix, HDS servers, OVHcloud)
 - `scw` (Paris, [Scaleway DC5](https://www.clever-cloud.com/blog/press/2023/01/17/clever-cloud-and-scaleway-join-forces-to-unveil-a-sovereign-european-paas-offering/))
-- `jed` (Jeddah, Oracle Cloud)
 - `mtl` (Montreal, OVHcloud)
 - `sgp` (Singapore, OVHcloud)
 - `syd` (Sydney, OVHcloud)

package/bin/clever.js

@@ -90,7 +90,10 @@ function run () {
       description: 'Application ID (or name, if unambiguous)',
       parser: Parsers.appIdOrName,
     }),
-    appNameCreation: cliparse.argument('app-name', { description: 'Application name' }),
+    appNameCreation: cliparse.argument('app-name', {
+      description: 'Application name (optional, current directory name is used if not specified)',
+      default: '',
+    }),
     backupId: cliparse.argument('backup-id', { description: 'A Database backup ID (format: UUID)' }),
     databaseId: cliparse.argument('database-id', { description: 'Any database ID (format: addon_UUID, postgresql_UUID, mysql_UUID, ...)' }),
     drainId: cliparse.argument('drain-id', { description: 'Drain ID' }),
@@ -132,6 +135,7 @@ function run () {
     sourceableEnvVarsList: cliparse.flag('add-export', { description: 'Display sourceable env variables setting' }),
     accesslogsFormat: getOutputFormatOption(['simple', 'extended', 'clf']),
     addonEnvFormat: getOutputFormatOption(['shell']),
+    logsFormat: getOutputFormatOption(['json-stream']),
     accesslogsFollow: cliparse.flag('follow', {
       aliases: ['f'],
       description: 'Display access logs continuously (ignores before/until, after/since)',
@@ -165,7 +169,7 @@ function run () {
       metavar: 'before',
       aliases: ['until'],
       parser: Parsers.date,
-      description: 'Fetch logs before this date/time (ISO8601)',
+      description: 'Fetch logs before this date/time (ISO8601 date or duration, positive number in seconds or duration Ex: 1h)',
     }),
     branch: cliparse.option('branch', {
       aliases: ['b'],
@@ -180,6 +184,12 @@ function run () {
       metavar: 'commit id',
       description: 'Restart the application with a specific commit ID',
     }),
+    gitTag: cliparse.option('tag', {
+      aliases: ['t'],
+      default: '',
+      metavar: 'tag',
+      description: 'Tag to push (none by default)',
+    }),
     databaseId: cliparse.option('database-id', {
       metavar: 'database_id',
       description: 'The Database ID (e.g.: postgresql_xxx)',
@@ -300,7 +310,7 @@ function run () {
     }),
     addonPlan: cliparse.option('plan', {
       aliases: ['p'],
-      default: 'dev',
+      default: '',
       metavar: 'plan',
       description: 'Addon plan, depends on the provider',
       complete: Addon('completePlan'),
@@ -345,11 +355,17 @@ function run () {
       parser: Parsers.commaSeparated,
     }),
     showAllActivity: cliparse.flag('show-all', { description: 'Show all activity' }),
-    showAll: cliparse.flag('show-all', { description: 'Show all available dependencies' }),
+    showAll: cliparse.flag('show-all', { description: 'Show all available add-ons and applications' }),
     loginToken: cliparse.option('token', {
       metavar: 'token',
       description: 'Directly give an existing token',
     }),
+    taskCommand: cliparse.option('task', {
+      description: 'The application launch as a task executing the given command, then stopped',
+      aliases: ['T'],
+      parser: Parsers.nonEmptyString,
+      metavar: 'command',
+    }),
     instanceType: cliparse.option('type', {
       aliases: ['t'],
       required: true,
@@ -367,6 +383,12 @@ function run () {
       metavar: 'api_key',
       description: 'Drain custom key',
     }),
+    drainIndexPrefix: cliparse.option('index-prefix', {
+      aliases: ['i'],
+      metavar: 'index_prefix',
+      description: 'Optional drain index prefix for ElasticSearch: `<indexPrefix>-<YYYY-MM-DD>`',
+      default: 'logstash-<YYYY-MM-DD>',
+    }),
     verbose: cliparse.flag('verbose', { aliases: ['v'], description: 'Verbose output' }),
     withoutCache: cliparse.flag('without-cache', { description: 'Restart the application without using cache' }),
     confirmAddonCreation: cliparse.flag('yes', {
@@ -559,7 +581,7 @@ function run () {
   const addonCreateCommand = cliparse.command('create', {
     description: 'Create an addon',
     args: [args.addonProvider, args.addonName],
-    options: [opts.linkAddon, opts.confirmAddonCreation, opts.addonPlan, opts.addonRegion, opts.addonVersion, opts.addonOptions],
+    options: [opts.linkAddon, opts.confirmAddonCreation, opts.addonPlan, opts.addonRegion, opts.addonVersion, opts.addonOptions, opts.humanJsonOutputFormat],
   }, addon('create'));
   const addonDeleteCommand = cliparse.command('delete', {
     description: 'Delete an addon',
@@ -586,7 +608,7 @@ function run () {
 
   const addonCommands = cliparse.command('addon', {
     description: 'Manage addons',
-    options: [opts.orgaIdOrName],
+    options: [opts.orgaIdOrName, opts.humanJsonOutputFormat],
     commands: [addonCreateCommand, addonDeleteCommand, addonRenameCommand, addonProvidersCommand, addonEnvCommand],
   }, addon('list'));
 
@@ -629,9 +651,15 @@ function run () {
   const appCreateCommand = cliparse.command('create', {
     description: 'Create an application',
     args: [args.appNameCreation],
-    options: [opts.instanceType, opts.orgaIdOrName, opts.aliasCreation, opts.region, opts.github, opts.humanJsonOutputFormat],
+    options: [opts.instanceType, opts.orgaIdOrName, opts.aliasCreation, opts.region, opts.github, opts.humanJsonOutputFormat, opts.taskCommand],
   }, create('create'));
 
+  // CURL COMMAND
+  // NOTE: it's just here for documentation purposes, look at the bottom of the file for the real "clever curl" command
+  const curlCommand = cliparse.command('curl', {
+    description: 'Query Clever Cloud\'s API using Clever Tools credentials',
+  }, () => null);
+
   // DELETE COMMAND
   const deleteCommandModule = lazyRequirePromiseModule('../src/commands/delete.js');
   const deleteCommand = cliparse.command('delete', {
@@ -643,7 +671,7 @@ function run () {
   const deploy = lazyRequirePromiseModule('../src/commands/deploy.js');
   const deployCommand = cliparse.command('deploy', {
     description: 'Deploy an application',
-    options: [opts.alias, opts.branch, opts.quiet, opts.forceDeploy, opts.followDeployLogs, opts.sameCommitPolicy],
+    options: [opts.alias, opts.branch, opts.gitTag, opts.quiet, opts.forceDeploy, opts.followDeployLogs, opts.sameCommitPolicy],
   }, deploy('deploy'));
 
   // DIAG COMMAND
@@ -685,7 +713,7 @@ function run () {
   const drainCreateCommand = cliparse.command('create', {
     description: 'Create a drain',
     args: [args.drainType, args.drainUrl],
-    options: [opts.addonId, opts.drainUsername, opts.drainPassword, opts.drainAPIKey],
+    options: [opts.addonId, opts.drainUsername, opts.drainPassword, opts.drainAPIKey, opts.drainIndexPrefix],
   }, drain('create'));
   const drainRemoveCommand = cliparse.command('remove', {
     description: 'Remove a drain',
@@ -754,7 +782,7 @@ function run () {
   const logs = lazyRequirePromiseModule('../src/commands/logs.js');
   const logsCommand = cliparse.command('logs', {
     description: 'Fetch application logs, continuously',
-    options: [opts.alias, opts.before, opts.after, opts.search, opts.deploymentId, opts.addonId],
+    options: [opts.alias, opts.before, opts.after, opts.search, opts.deploymentId, opts.addonId, opts.logsFormat],
   }, logs('appLogs'));
 
   // MAKE DEFAULT COMMAND
@@ -1021,7 +1049,7 @@ function run () {
   const backupsCommand = cliparse.command('backups', {
     description: 'List available database backups',
     args: [args.databaseId],
-    options: [opts.orgaIdOrName],
+    options: [opts.orgaIdOrName, opts.humanJsonOutputFormat],
     commands: [
       downloadBackupCommand,
     ],
@@ -1035,6 +1063,9 @@ function run () {
     console.info('clever database backups download');
   });
 
+  // Patch help command description
+  cliparseCommands.helpCommand.description = 'Display help about the Clever Cloud CLI';
+
   const commands = _sortBy([
     accesslogsCommand,
     activityCommand,
@@ -1045,6 +1076,7 @@ function run () {
     appUnlinkCommand,
     cancelDeployCommand,
     configCommands,
+    curlCommand,
     databaseCommand,
     deleteCommand,
     deployCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clever-tools",
-  "version": "3.2.0",
+  "version": "3.5.0",
   "description": "Command Line Interface for Clever Cloud.",
   "main": "bin/clever.js",
   "keywords": [
@@ -25,14 +25,16 @@
     "scripts/*.sh"
   ],
   "dependencies": {
-    "@clevercloud/client": "^8.1.0",
+    "@clevercloud/client": "^8.1.2",
     "clf-date": "^0.2.0",
     "cliparse": "^0.3.3",
     "colors": "1.4.0",
     "common-env": "^6.4.0",
-    "curlconverter": "^3.21.0",
+    "curlconverter": "^4.9.0",
+    "duration-js": "^4.0.0",
     "eventsource": "^1.1.0",
-    "isomorphic-git": "^1.25.0",
+    "iso8601-duration": "^2.1.2",
+    "isomorphic-git": "^1.25.3",
     "linux-release-info": "^3.0.0",
     "lodash": "^4.17.21",
     "mkdirp": "^1.0.4",

package/src/commands/addon.js

@@ -15,63 +15,141 @@ const { sendToApi } = require('../models/send-to-api.js');
 const { toNameEqualsValueString } = require('@clevercloud/client/cjs/utils/env-vars.js');
 const { resolveAddonId } = require('../models/ids-resolver.js');
 
+function getPlan (inputPlan, providerName) {
+
+  // Return user plan
+  if (inputPlan !== '') {
+    return inputPlan;
+  }
+
+  // Choose a default plan based on the add-on provider
+  switch (providerName) {
+    case 'kv':
+      return 'alpha';
+    default:
+      return 'dev';
+  }
+}
+
 async function list (params) {
-  const { org: orgaIdOrName } = params.options;
+  const { org: orgaIdOrName, format } = params.options;
 
   const ownerId = await Organisation.getId(orgaIdOrName);
   const addons = await Addon.list(ownerId);
 
-  const formattedAddons = addons.map((addon) => {
-    return [
-      addon.plan.name + ' ' + addon.provider.name,
-      addon.region,
-      colors.bold.green(addon.name),
-      addon.id,
-    ];
-  });
-  Logger.println(formatTable(formattedAddons));
+  switch (format) {
+    case 'json': {
+      const formattedAddons = addons.map((addon) => {
+        return {
+          addonId: addon.id,
+          creationDate: addon.creationDate,
+          name: addon.name,
+          planName: addon.plan.name,
+          planSlug: addon.plan.slug,
+          providerId: addon.provider.id,
+          realId: addon.realId,
+          region: addon.region,
+          type: addon.provider.name,
+        };
+      });
+      Logger.printJson(formattedAddons);
+      break;
+    }
+    case 'human':
+    default: {
+      const formattedAddons = addons.map((addon) => {
+        return [
+          addon.plan.name + ' ' + addon.provider.name,
+          addon.region,
+          colors.bold.green(addon.name),
+          addon.id,
+        ];
+      });
+      Logger.println(formatTable(formattedAddons));
+    }
+  }
 }
 
 async function create (params) {
   const [providerName, name] = params.args;
-  const { link: linkedAppAlias, plan: planName, region, yes: skipConfirmation, org: orgaIdOrName } = params.options;
+  const {
+    link: linkedAppAlias,
+    plan: inputPlan,
+    region,
+    yes: skipConfirmation,
+    org: orgaIdOrName,
+    format,
+  } = params.options;
   const version = params.options['addon-version'];
   const addonOptions = parseAddonOptions(params.options.option);
+  const planName = getPlan(inputPlan, providerName);
 
   const ownerId = (orgaIdOrName != null)
     ? await Organisation.getId(orgaIdOrName)
     : await User.getCurrentId();
 
+  const addonToCreate = {
+    ownerId,
+    name,
+    providerName,
+    planName,
+    region,
+    skipConfirmation,
+    version,
+    addonOptions,
+  };
+
   if (linkedAppAlias != null) {
     const linkedAppData = await AppConfig.getAppDetails({ alias: linkedAppAlias });
-    if (orgaIdOrName != null && linkedAppData.ownerId !== ownerId) {
+    if (orgaIdOrName != null && linkedAppData.ownerId !== ownerId && format === 'human') {
       Logger.warn('The specified application does not belong to the specified organisation. Ignoring the `--org` option');
     }
     const newAddon = await Addon.create({
+      ...addonToCreate,
       ownerId: linkedAppData.ownerId,
-      name,
-      providerName,
-      planName,
-      region,
-      skipConfirmation,
-      version,
-      addonOptions,
     });
     await Addon.link(linkedAppData.ownerId, linkedAppData.appId, { addon_id: newAddon.id });
-    Logger.println(`Addon ${name} (id: ${newAddon.id}) successfully created and linked to the application`);
+    displayAddon(format, newAddon, providerName, `Add-on created and linked to application ${linkedAppAlias} successfully!`);
   }
   else {
-    const newAddon = await Addon.create({
-      ownerId,
-      name,
-      providerName,
-      planName,
-      region,
-      skipConfirmation,
-      version,
-      addonOptions,
-    });
-    Logger.println(`Addon ${name} (id: ${newAddon.id}) successfully created`);
+    const newAddon = await Addon.create(addonToCreate);
+    displayAddon(format, newAddon, providerName, 'Add-on created successfully!');
+  }
+}
+
+function displayAddon (format, addon, providerName, message) {
+  switch (format) {
+
+    case 'json': {
+      const jsonAddon = {
+        id: addon.id,
+        realId: addon.realId,
+        name: addon.name,
+      };
+      Logger.printJson((providerName === 'kv')
+        ? { ...jsonAddon, availability: 'alpha', warning: 'Don\'t store sensitive or production grade data' }
+        : jsonAddon);
+      break;
+    }
+
+    case 'human':
+    default:
+      Logger.println([
+        message,
+        `ID: ${addon.id}`,
+        `Real ID: ${addon.realId}`,
+        `Name: ${addon.name}`,
+      ].join('\n'));
+      if (providerName === 'kv') {
+        const materiaMessage = [
+          '',
+          colors.yellow(`/!\\ The MateriaDB ${providerName.toUpperCase()} provider is in Alpha testing phase, don't store sensitive or production grade data`),
+          'You can easily use MateriaDB KV with \'redis-cli\', with such commands:',
+          colors.blue(`source <(clever addon env ${addon.id} -F shell)`),
+          colors.blue('redis-cli -h $KV_HOST -p $KV_PORT'),
+        ].join('\n');
+        Logger.println(materiaMessage);
+      }
   }
 }
 

package/src/commands/create.js

@@ -1,31 +1,53 @@
 'use strict';
 
+const path = require('path');
 const Application = require('../models/application.js');
 const AppConfig = require('../models/app_configuration.js');
 const Logger = require('../logger.js');
 
 async function create (params) {
   const { type: typeName } = params.options;
-  const [name] = params.args;
-  const { org: orgaIdOrName, alias, region, github: githubOwnerRepo, format } = params.options;
+  const [rawName] = params.args;
+  const { org: orgaIdOrName, alias, region, github: githubOwnerRepo, format, task: taskCommand } = params.options;
   const { apps } = await AppConfig.loadApplicationConf();
 
+  // Application name is optionnal, use current directory name if not specified (empty string)
+  const name = (rawName !== '') ? rawName : getCurrentDirectoryName();
+
+  const isTask = (taskCommand != null);
+  const envVars = isTask
+    ? { CC_RUN_COMMAND: taskCommand }
+    : {};
+
   AppConfig.checkAlreadyLinked(apps, name, alias);
 
   const github = getGithubDetails(githubOwnerRepo);
-  const app = await Application.create(name, typeName, region, orgaIdOrName, github);
+  const app = await Application.create(name, typeName, region, orgaIdOrName, github, isTask, envVars);
   await AppConfig.addLinkedApplication(app, alias);
 
   switch (format) {
-
     case 'json': {
-      console.log(JSON.stringify(app, null, 2));
+      Logger.printJson({
+        id: app.id,
+        name: app.name,
+        executedAs: app.instance.lifetime,
+        env: app.env,
+        deployUrl: app.deployUrl,
+      });
       break;
     }
 
     case 'human':
     default:
-      Logger.println('Your application has been successfully created!');
+      if (isTask) {
+        Logger.println('Your application has been successfully created as a task!');
+        Logger.println(`The "CC_RUN_COMMAND" environment variable has been set to "${taskCommand}"`);
+      }
+      else {
+        Logger.println('Your application has been successfully created!');
+      }
+      Logger.println(`ID: ${app.id}`);
+      Logger.println(`Name: ${name}`);
   }
 };
 
@@ -36,4 +58,8 @@ function getGithubDetails (githubOwnerRepo) {
   }
 }
 
+function getCurrentDirectoryName () {
+  return path.basename(process.cwd());
+}
+
 module.exports = { create };

package/src/commands/curl.js

@@ -1,9 +1,10 @@
 'use strict';
 
-const { parseCurlCommand } = require('curlconverter/util.js');
 const { spawn } = require('child_process');
 const { loadOAuthConf, conf } = require('../models/configuration.js');
 const { addOauthHeader } = require('@clevercloud/client/cjs/oauth.js');
+const Logger = require('../logger.js');
+const colors = require('colors/safe');
 
 async function loadTokens () {
   const tokens = await loadOAuthConf();
@@ -15,37 +16,86 @@ async function loadTokens () {
   };
 }
 
+function printCleverCurlHelp () {
+  const apiDocUrlv2 = 'https://developers.clever-cloud.com/api/v2/';
+  const apiDocUrlv4 = 'https://developers.clever-cloud.com/api/v4/';
+
+  Logger.println(`Usage: clever curl
+Query Clever Cloud's API using Clever Tools credentials. For example: 
+
+  clever curl ${conf.API_HOST}/v2/self
+  clever curl ${conf.API_HOST}/v2/summary
+  clever curl ${conf.API_HOST}/v4/products/zones
+  clever curl ${conf.API_HOST}/v2/organisations/<ORGANISATION_ID>/applications | jq '.[].id'
+  clever curl ${conf.API_HOST}/v4/billing/organisations/<ORGANISATION_ID>/<INVOICE_NUMBER>.pdf > invoice.pdf
+
+Our API documentation is available here : 
+
+  ${apiDocUrlv2}
+  ${apiDocUrlv4}`);
+}
+
 async function curl () {
 
-  // We have to add single quotes on values for the parser
-  const curlString = process.argv
-    .slice(2)
-    .map((str) => !str.startsWith('-') ? `'${str}'` : str)
-    .join(' ');
+  // We remove the first three args: "node", "clever" and "curl"
+  const curlArgs = process.argv.slice(3);
+  const hasNoArgs = curlArgs.length === 0;
+  const startsWithHelpArg = curlArgs[0] === '--help' || curlArgs[0] === '-h';
+  const shouldDisplayCleverCurlHelp = hasNoArgs || startsWithHelpArg;
 
-  const curlDetails = parseCurlCommand(curlString);
+  if (shouldDisplayCleverCurlHelp) {
+    printCleverCurlHelp();
+    return;
+  }
 
-  const tokens = await loadTokens();
+  const requestParams = await parseCurlCommand(['curl', ...curlArgs]);
 
-  const requestParams = {
-    method: curlDetails.method,
-    url: curlDetails.urlWithoutQuery,
-    headers: curlDetails.headers,
-    queryParams: curlDetails.query,
-  };
+  // We only allow request to the respective API_HOST
+  if (!requestParams.url.startsWith(conf.API_HOST)) {
+    Logger.error('"clever curl" command must be used with ' + colors.blue(conf.API_HOST));
+    process.exit(1);
+  }
+
+  const lastCurlArg = curlArgs.at(-1);
+  const lastCurlArgIsHelp = lastCurlArg !== '--help' && lastCurlArg !== '-h';
+
+  // Add oAuth header, only if last cURL arg is not help
+  // We do this because cURL's help arg expect a category
+  if (lastCurlArgIsHelp) {
 
-  const oauthHeader = await Promise.resolve(requestParams)
-    .then(addOauthHeader(tokens))
-    .then((request) => request.headers.Authorization);
+    const tokens = await loadTokens();
+    const oauthHeader = await Promise.resolve(requestParams)
+      .then(addOauthHeader(tokens))
+      .then((request) => request.headers.Authorization);
 
-  // Reuse raw curl command
-  const curlParams = process.argv.slice(3);
+    curlArgs.push('-H', `Authorization: ${oauthHeader}`);
+  }
 
-  // Add oauth
-  curlParams.push('-H', `Authorization: ${oauthHeader}`);
+  spawn('curl', curlArgs, { stdio: 'inherit' });
 
-  spawn('curl', curlParams, { stdio: 'inherit' });
+}
+
+async function parseCurlCommand (curlCommand) {
+
+  const curlParser = await import('curlconverter/dist/src/parse.js');
+
+  const [request] = curlParser.parse(curlCommand);
+  const url = request.urls[0];
+
+  return {
+    method: url.method.toString(),
+    url: url.urlWithoutQueryArray.toString(),
+    headers: transformCurlConverterWordsToObject(request.headers.headers),
+    queryParams: transformCurlConverterWordsToObject(url.queryDict),
+  };
+}
 
+function transformCurlConverterWordsToObject (words = []) {
+  return Object.fromEntries(
+    words.map(([key, value]) => {
+      return [key.toString(), value.toString()];
+    }),
+  );
 }
 
 module.exports = { curl };

package/src/commands/database.js

@@ -7,41 +7,63 @@ const formatTable = require('../format-table')();
 const superagent = require('superagent');
 const fs = require('fs');
 const { findOwnerId } = require('../models/addon.js');
-const { resolveRealId } = require('../models/ids-resolver.js');
+const { resolveRealId, resolveAddonId } = require('../models/ids-resolver.js');
+const Logger = require('../logger.js');
 
 async function listBackups (params) {
 
-  const { org } = params.options;
+  const { org, format } = params.options;
   const [addonIdOrRealId] = params.args;
 
-  const addonId = await resolveRealId(addonIdOrRealId);
-  const ownerId = await findOwnerId(org, addonId);
+  const realId = await resolveRealId(addonIdOrRealId);
+  const addonId = await resolveAddonId(addonIdOrRealId);
+  const ownerId = await findOwnerId(org, realId);
 
-  const backups = await getBackups({ ownerId, ref: addonId }).then(sendToApi);
+  const backups = await getBackups({ ownerId, ref: realId }).then(sendToApi);
 
-  if (backups.length === 0) {
+  if (backups.length === 0 && format === 'human') {
     println('There are no backups yet');
     return;
   }
 
-  const formattedLines = backups
-    .sort((a, b) => a.creation_date.localeCompare(b.creation_date))
-    .map((backup) => [
-      backup.backup_id,
-      backup.creation_date,
-      backup.status,
-    ]);
-
-  const head = [
-    'BACKUP ID',
-    'CREATION DATE',
-    'STATUS',
-  ];
-
-  println(formatTable([
-    head,
-    ...formattedLines,
-  ]));
+  const sortedBackups = backups.sort((a, b) => a.creation_date.localeCompare(b.creation_date));
+
+  switch (format) {
+    case 'json': {
+      const formattedBackups = sortedBackups.map((backup) => {
+        return {
+          addonId: addonId,
+          backupId: backup.backup_id,
+          creationDate: backup.creation_date,
+          downloadUrl: backup.download_url,
+          ownerId: ownerId,
+          realId: realId,
+          status: backup.status,
+        };
+      });
+      Logger.printJson(formattedBackups);
+      break;
+    }
+    case 'human': {
+      const formattedLines = sortedBackups
+        .map((backup) => [
+          backup.backup_id,
+          backup.creation_date,
+          backup.status,
+        ]);
+
+      const head = [
+        'BACKUP ID',
+        'CREATION DATE',
+        'STATUS',
+      ];
+
+      println(formatTable([
+        head,
+        ...formattedLines,
+      ]));
+    }
+  }
 }
 
 async function downloadBackups (params) {

package/src/commands/deploy.js

@@ -13,12 +13,12 @@ const { sendToApi } = require('../models/send-to-api.js');
 // Once the API call to redeploy() has been triggered successfully,
 // the rest (waiting for deployment state to evolve and displaying logs) is done with auto retry (resilient to network failures)
 async function deploy (params) {
-  const { alias, branch: branchName, quiet, force, follow, 'same-commit-policy': sameCommitPolicy } = params.options;
+  const { alias, branch: branchName, tag: tagName, quiet, force, follow, 'same-commit-policy': sameCommitPolicy } = params.options;
 
   const appData = await AppConfig.getAppDetails({ alias });
   const { ownerId, appId } = appData;
-  const branchRefspec = await git.getFullBranch(branchName);
 
+  const branchRefspec = await getBranchToDeploy(branchName, tagName);
   const commitIdToPush = await git.getBranchCommit(branchRefspec);
   const remoteHeadCommitId = await git.getRemoteCommit(appData.deployUrl);
   const deployedCommitId = await Application.get(ownerId, appId)
@@ -66,7 +66,8 @@ async function deploy (params) {
   const knownDeployments = await getAllDeployments({ id: ownerId, appId, limit: 5 }).then(sendToApi);
 
   Logger.println('Pushing source code to Clever Cloud…');
-  await git.push(appData.deployUrl, branchRefspec, force)
+
+  await git.push(appData.deployUrl, commitIdToPush, force)
     .catch(async (e) => {
       const isShallow = await git.isShallow();
       if (isShallow) {
@@ -86,4 +87,20 @@ async function restartOnSameCommit (ownerId, appId, commitIdToPush, quiet, follo
   return Log.watchDeploymentAndDisplayLogs({ ownerId, appId, deploymentId: restart.deploymentId, quiet, follow });
 }
 
+async function getBranchToDeploy (branchName, tagName) {
+  if (tagName) {
+    const useTag = await git.isExistingTag(tagName);
+    if (useTag) {
+      const tagRefspec = await git.getFullBranch(tagName);
+      return tagRefspec;
+    }
+    else {
+      throw new Error(`Tag ${tagName} doesn't exist locally`);
+    }
+  }
+  else {
+    return await git.getFullBranch(branchName);
+  }
+}
+
 module.exports = { deploy };

package/src/commands/drain.js

@@ -25,16 +25,22 @@ async function list (params) {
   }
 
   drains.forEach((drain) => {
-    const { id, state, target: { url, drainType } } = drain;
-    Logger.println(`${id} -> ${state} for ${url} as ${drainType}`);
+    const { id, state, target } = drain;
+    const { url, drainType, indexPrefix } = target;
+
+    let drainView = `${id} -> ${state} for ${url} as ${drainType}`;
+    if (indexPrefix != null) {
+      drainView += `, index: '${indexPrefix}-<YYYY-MM-DD>'`;
+    }
+    Logger.println(drainView);
   });
 }
 
 async function create (params) {
   const [drainTargetType, drainTargetURL] = params.args;
-  const { alias, addon: addonId, username, password, 'api-key': apiKey } = params.options;
+  const { alias, addon: addonId, username, password, 'api-key': apiKey, 'index-prefix': indexPrefix } = params.options;
   const drainTargetCredentials = { username, password };
-  const drainTargetConfig = { apiKey };
+  const drainTargetConfig = { apiKey, indexPrefix };
 
   const appIdOrAddonId = await getAppOrAddonId({ alias, addonId });
   const body = createDrainBody(appIdOrAddonId, drainTargetURL, drainTargetType, drainTargetCredentials, drainTargetConfig);

package/src/commands/logs.js

@@ -5,26 +5,36 @@ const LogV2 = require('../models/log.js');
 const Log = require('../models/log-v4.js');
 const Logger = require('../logger.js');
 const { Deferred } = require('../models/utils.js');
+const colors = require('colors/safe');
+const { resolveAddonId } = require('../models/ids-resolver.js');
 
 async function appLogs (params) {
-  const { alias, after: since, before: until, search, 'deployment-id': deploymentId } = params.options;
+  const { alias, addon: addonIdOrRealId, after: since, before: until, search, 'deployment-id': deploymentId, format } = params.options;
 
   // ignore --search ""
   const filter = (search !== '') ? search : null;
+  const isForHuman = (format === 'human');
 
-  const { appId, ownerId } = await AppConfig.getAppDetails({ alias });
+  // TODO: drop when addons are migrated to the v4 API
+  if (addonIdOrRealId != null) {
+    const addonId = await resolveAddonId(addonIdOrRealId);
+    if (isForHuman) {
+      Logger.println(colors.blue('Waiting for addon logs…'));
+    }
+    else {
+      throw new Error(`"${format}" format is not yet available for add-on logs`);
+    }
+    return LogV2.displayLogs({ appAddonId: addonId, since, until, filter, deploymentId });
+  }
 
-  Logger.println('Waiting for application logs…');
+  const { appId, ownerId } = await AppConfig.getAppDetails({ alias });
 
-  // TODO: drop when addons are migrated to the v4 API
-  if (params.addon) {
-    const { addon: addonId } = params.options;
-    const appAddonId = addonId || await AppConfig.getAppDetails({ alias }).then(({ appId }) => appId);
-    return LogV2.displayLogs({ appAddonId, since, until, filter, deploymentId });
+  if (isForHuman) {
+    Logger.println(colors.blue('Waiting for application logs…'));
   }
 
   const deferred = new Deferred();
-  await Log.displayLogs({ ownerId, appId, since, until, filter, deploymentId, deferred });
+  await Log.displayLogs({ ownerId, appId, since, until, filter, deploymentId, format, deferred });
   return deferred.promise;
 }
 

package/src/commands/status.js

@@ -35,11 +35,12 @@ function computeStatus (instances, app) {
     : colors.bold.red('stopped');
 
   const statusLine = `${app.name}: ${statusMessage}`;
+  const taskLine = `Executed as: ${colors.bold(app.instance.lifetime)}`;
   const deploymentLine = isDeploying
     ? `Deployment in progress ${displayGroupInfo(deployingInstances, deployingCommit)}`
     : '';
 
-  return [statusLine, deploymentLine].join('\n');
+  return [statusLine, taskLine, deploymentLine].join('\n');
 }
 
 function displayScalability (app) {

package/src/logger.js

@@ -52,6 +52,11 @@ const Logger = _(['debug', 'info', 'warn', 'error'])
 // No decoration for Logger.println
 Logger.println = console.log;
 
+// No decoration for Logger.println
+Logger.printJson = (obj) => {
+  console.log(JSON.stringify(obj, null, 2));
+};
+
 // No decoration for Logger.printErrorLine
 Logger.printErrorLine = console.error;
 

package/src/models/application.js

@@ -17,7 +17,7 @@ function listAvailableTypes () {
   return autocomplete.words(['docker', 'elixir', 'go', 'gradle', 'haskell', 'jar', 'maven', 'meteor', 'node', 'php', 'play1', 'play2', 'python', 'ruby', 'rust', 'sbt', 'static-apache', 'war']);
 };
 
-const AVAILABLE_ZONES = ['par', 'rbx', 'rbxhds', 'scw', 'jed', 'mtl', 'sgp', 'syd', 'wsw'];
+const AVAILABLE_ZONES = ['par', 'grahds', 'rbx', 'rbxhds', 'scw', 'mtl', 'sgp', 'syd', 'wsw'];
 
 function listAvailableZones () {
   return autocomplete.words(AVAILABLE_ZONES);
@@ -53,7 +53,7 @@ async function getInstanceType (type) {
   return instanceVariant;
 };
 
-async function create (name, typeName, region, orgaIdOrName, github) {
+async function create (name, typeName, region, orgaIdOrName, github, isTask, envVars) {
   Logger.debug('Create the application…');
 
   const ownerId = (orgaIdOrName != null)
@@ -74,6 +74,8 @@ async function create (name, typeName, region, orgaIdOrName, github) {
     minInstances: 1,
     name: name,
     zone: region,
+    instanceLifetime: isTask ? 'TASK' : 'REGULAR',
+    env: envVars,
   };
 
   if (github != null) {

package/src/models/drain.js

@@ -6,7 +6,7 @@ const DRAIN_TYPES = [
   { id: 'TCPSyslog' },
   { id: 'UDPSyslog' },
   { id: 'HTTP', credentials: 'OPTIONAL' },
-  { id: 'ElasticSearch', credentials: 'MANDATORY' },
+  { id: 'ElasticSearch', credentials: 'MANDATORY', indexPrefix: 'OPTIONAL' },
   { id: 'DatadogHTTP' },
   { id: 'NewRelicHTTP', apiKey: 'MANDATORY' },
 ];
@@ -30,14 +30,18 @@ function createDrainBody (appId, drainTargetURL, drainTargetType, drainTargetCre
   if (keyExist(drainTargetConfig)) {
     body.APIKey = drainTargetConfig.apiKey;
   }
+  if (indexPrefixExist(drainTargetConfig)) {
+    body.indexPrefix = drainTargetConfig.indexPrefix;
+  }
   return body;
 }
 
 function authorizeDrainCreation (drainTargetType, drainTargetCredentials, drainTargetConfig) {
   if (drainTypeExists(drainTargetType)) {
-    // retrieve creds for drain type ('mandatory', 'optional', undefined)
-    const credStatus = credentialsStatus(drainTargetType).credentials;
-    const keyStatus = credentialsStatus(drainTargetType).apiKey;
+    // retrieve field for drain type ('mandatory', 'optional', undefined)
+    const credStatus = fieldStatus(drainTargetType).credentials;
+    const keyStatus = fieldStatus(drainTargetType).apiKey;
+    const indexPrefixStatus = fieldStatus(drainTargetType).indexPrefix;
 
     if (credStatus === 'MANDATORY') {
       return credentialsExist(drainTargetCredentials);
@@ -58,10 +62,20 @@ function authorizeDrainCreation (drainTargetType, drainTargetCredentials, drainT
     if (!keyStatus) {
       return keyEmpty(drainTargetConfig);
     }
+
+    if (indexPrefixStatus === 'MANDATORY') {
+      return indexPrefixExist(drainTargetConfig);
+    }
+    if (indexPrefixStatus === 'OPTIONAL') {
+      return true;
+    }
+    if (!indexPrefixStatus) {
+      return indexPrefixEmpty(drainTargetConfig);
+    }
   }
 }
 
-function credentialsStatus (drainTargetType) {
+function fieldStatus (drainTargetType) {
   return DRAIN_TYPES.find(({ id }) => id === drainTargetType);
 }
 
@@ -77,6 +91,14 @@ function credentialsEmpty ({ username, password }) {
   return username == null && password == null;
 }
 
+function indexPrefixExist ({ indexPrefix }) {
+  return indexPrefix != null;
+}
+
+function indexPrefixEmpty ({ indexPrefix }) {
+  return indexPrefix == null;
+}
+
 function keyExist ({ apiKey }) {
   return apiKey != null;
 }

package/src/models/git.js

@@ -78,7 +78,19 @@ async function getFullBranch (branchName) {
 
 async function getBranchCommit (refspec) {
   const repo = await getRepo();
-  return git.resolveRef({ ...repo, ref: refspec });
+  const oid = await git.resolveRef({ ...repo, ref: refspec });
+  // When a refspec refers to an annotated tag, the OID ref represents the annotation and not the commit directly,
+  // that's why we need a call to `readCommit`.
+  const res = await git.readCommit({ ...repo, ref: refspec, oid });
+  return res.oid;
+}
+
+async function isExistingTag (tag) {
+  const repo = await getRepo();
+  const tags = await git.listTags({
+    ...repo,
+  });
+  return tags.includes(tag);
 }
 
 async function push (remoteUrl, branchRefspec, force) {
@@ -131,4 +143,5 @@ module.exports = {
   push,
   completeBranches,
   isShallow,
+  isExistingTag,
 };

package/src/models/log-v4.js

@@ -18,7 +18,11 @@ async function displayLogs (params) {
 
   const deferred = params.deferred || new Deferred();
   const { apiHost, tokens } = await getHostAndTokens();
-  const { ownerId, appId, filter, since, until, deploymentId } = params;
+  const { ownerId, appId, filter, since, until, deploymentId, format } = params;
+
+  if (format === 'json' && until == null) {
+    throw new Error('"json" format is only applicable with a limiting parameter such as `--until`');
+  }
 
   const logStream = new ApplicationLogStream({
     apiHost,
@@ -37,21 +41,40 @@ async function displayLogs (params) {
 
   // Properly close the stream
   process.once('SIGINT', (signal) => logStream.close(signal));
+  const jsonArray = new JsonArray();
 
   logStream
     .on('open', (event) => {
       Logger.debug(colors.blue(`Logs stream (open) ${JSON.stringify({ appId, filter, deploymentId })}`));
+      if (format === 'json') {
+        jsonArray.open();
+      }
     })
     .on('error', (event) => {
       Logger.debug(colors.red(`Logs stream (error) ${event.error.message}`));
     })
     .onLog((log) => {
-      Logger.println(formatLogLine(log));
+      switch (format) {
+        case 'json':
+          jsonArray.push(log);
+          return;
+        case 'json-stream':
+          Logger.printJson(log);
+          return;
+        case 'human':
+        default:
+          Logger.println(formatLogLine(log));
+      }
     });
 
   // start() is blocking until end of stream
   logStream.start()
-    .then((reason) => deferred.resolve())
+    .then((reason) => {
+      if (format === 'json') {
+        jsonArray.close();
+      }
+      return deferred.resolve();
+    })
     .catch(processError)
     .catch((error) => deferred.reject(error));
 
@@ -71,7 +94,8 @@ async function watchDeploymentAndDisplayLogs (options) {
     redeployDate,
   } = options;
 
-  Logger.println('Waiting for deployment to start…');
+  // If in quiet mode, we only log start/finished deployment messages
+  !quiet && Logger.println('Waiting for deployment to start…');
   const deployment = await waitForDeploymentStart({ ownerId, appId, deploymentId, commitId, knownDeployments });
   Logger.println(colors.bold.blue(`Deployment started (${deployment.uuid})`));
 
@@ -88,7 +112,7 @@ async function watchDeploymentAndDisplayLogs (options) {
     logsStream = await displayLogs({ ownerId, appId, deploymentId: deployment.uuid, since: redeployDate, deferred });
   }
 
-  Logger.println('Waiting for application logs…');
+  !quiet && Logger.println('Waiting for application logs…');
 
   // Wait for deployment end (or an error thrown by logs with the deferred)
   const deploymentEnded = await Promise.race([
@@ -142,3 +166,30 @@ function isBuildSucessMessage (log) {
 };
 
 module.exports = { displayLogs, watchDeploymentAndDisplayLogs };
+
+/**
+ * Helper to print a real JSON array with starting `[` and ending `]`
+ */
+class JsonArray {
+  constructor () {
+    this._isFirst = true;
+  }
+
+  open () {
+    process.stdout.write('[\n');
+  }
+
+  push (log) {
+    if (this._isFirst) {
+      this._isFirst = false;
+    }
+    else {
+      process.stdout.write(',\n');
+    }
+    process.stdout.write(`  ${JSON.stringify(log)}`);
+  }
+
+  close () {
+    process.stdout.write('\n]');
+  }
+}

package/src/parsers.js

@@ -3,6 +3,8 @@
 const cliparse = require('cliparse');
 
 const Application = require('./models/application.js');
+const ISO8601 = require('iso8601-duration');
+const Duration = require('duration-js');
 
 function flavor (flavor) {
   const flavors = Application.listAvailableFlavors();
@@ -32,10 +34,16 @@ function instances (instances) {
 
 function date (dateString) {
   const date = new Date(dateString);
-  if (isNaN(date.getTime())) {
-    return cliparse.parsers.error('Invalid date: ' + dateString + ' (timestamps or IS0 8601 dates are accepted)');
+  if (isNaN(dateString) && !isNaN(date.getTime())) {
+    return cliparse.parsers.success(date);
   }
-  return cliparse.parsers.success(date);
+
+  const duration = durationInSeconds(dateString);
+  if (duration.success) {
+    return cliparse.parsers.success(new Date(Date.now() - (duration.success * 1000)));
+  }
+
+  return duration;
 }
 
 const appIdRegex = /^app_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -86,6 +94,13 @@ function integer (string) {
   return cliparse.parsers.success(integer);
 }
 
+function nonEmptyString (string) {
+  if (typeof string !== 'string' || string === '') {
+    return cliparse.parsers.error('Invalid string, it should not be empty');
+  }
+  return cliparse.parsers.success(string);
+}
+
 // /^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/i;
 const tagRegex = /^[^,\s]+$/;
 
@@ -143,6 +158,39 @@ function portNumber (number) {
   return cliparse.parsers.error(`Invalid port number '${number}'. Should match ${portNumberRegex}`);
 }
 
+/**
+ * Parse a duration into seconds
+ * A Zero seconds duration is allowed
+ * @param {string} durationStr an ISO8601, 1h or a positive number
+ * @returns {number} number of seconds
+ */
+function durationInSeconds (durationStr = '') {
+  const failed = cliparse.parsers.error(`Invalid duration: "${durationStr}", expect (IS0 8601 duration / a "1h, 1m, 30s" like duration / a positive number in seconds)`);
+
+  if (durationStr.startsWith('P')) {
+    try {
+      const d = ISO8601.parse(durationStr);
+      return cliparse.parsers.success(ISO8601.toSeconds(d));
+    }
+    catch (err) {
+      return failed;
+    }
+  }
+
+  try {
+    const duration = Duration.parse(durationStr);
+    return cliparse.parsers.success(duration.seconds());
+  }
+  catch (err) {
+    const n = Number.parseInt(durationStr);
+    if (isNaN(n) || n < 0) {
+      return failed;
+    }
+
+    return cliparse.parsers.success(n);
+  }
+}
+
 module.exports = {
   buildFlavor,
   flavor,
@@ -162,4 +210,6 @@ module.exports = {
   ipAddress,
   portNumberRegex,
   portNumber,
+  durationInSeconds,
+  nonEmptyString,
 };