clever-tools 4.4.0 → 4.5.0

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

@@ -0,0 +1,173 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { defineArgument } from '../../lib/define-argument.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 AppConfig from '../../models/app_configuration.js';
+import * as Application from '../../models/application.js';
+import { AVAILABLE_ZONES, listAvailableTypes, listAvailableZones } from '../../models/application.js';
+import { conf } from '../../models/configuration.js';
+import { isGitWorkingDirectoryClean, isInsideGitRepo } from '../../models/git.js';
+import { aliasCreationOption, humanJsonOutputFormatOption, orgaIdOrNameOption } from '../global.options.js';
+
+function getGithubDetails(githubOwnerRepo) {
+  if (githubOwnerRepo != null) {
+    const [owner, name] = githubOwnerRepo.split('/');
+    return { owner, name };
+  }
+}
+
+function getCurrentDirectoryName() {
+  return path.basename(process.cwd());
+}
+
+async function displayAppCreation(app, alias, github, taskCommand) {
+  Logger.printSuccess(`Application ${styleText('green', app.name)} successfully created!`);
+
+  const hasDistinctAlias = alias != null && alias !== app.name;
+  const isTask = app.instance.lifetime === 'TASK';
+
+  Logger.println();
+  printFieldsAsTable(2, {
+    Type: styleText('blue', `⬢ ${app.instance.variant.name}`),
+    ID: app.id,
+    'Organisation ID': app.ownerId,
+    Name: app.name,
+    GitHub: github != null && `${github.owner}/${github.name}`,
+    Alias: hasDistinctAlias && alias,
+    Zone: app.zone,
+    Task: isTask && `"${taskCommand}"`,
+  });
+
+  Logger.println();
+  Logger.println('  ' + styleText('bold', 'Next steps:'));
+
+  if (!github) {
+    const isInsideGit = await isInsideGitRepo();
+    if (!isInsideGit) {
+      Logger.println(`  ${styleText('yellow', '!')} Initialize a git repository first, for example:`);
+      Logger.println(`    ${shellCommand('git init')}`);
+      Logger.println(`    ${shellCommand('git add .')}`);
+      Logger.println(`    ${shellCommand('git commit -m "Initial commit"')}`);
+      Logger.println();
+    } else {
+      const isClean = await isGitWorkingDirectoryClean();
+      if (!isClean) {
+        Logger.println(`  ${styleText('yellow', '!')} Commit your changes first:`);
+        Logger.println(`    ${shellCommand('git add .')}`);
+        Logger.println(`    ${shellCommand('git commit -m "My changes"')}`);
+        Logger.println();
+      }
+    }
+  }
+
+  if (github) {
+    Logger.println(
+      `  ${styleText('blue', '→')} Push changes to ${styleText('blue', `${github.owner}/${github.name}`)} GitHub repository to trigger a deployment, or ${styleText('blue', 'clever restart')} the latest pushed commit`,
+    );
+  } else {
+    Logger.println(
+      `  ${styleText('blue', '→')} Run ${styleText('blue', 'clever deploy')} ${isTask ? 'to execute your task' : 'to deploy your application'}`,
+    );
+  }
+
+  Logger.println(
+    `  ${styleText('blue', '→')} Manage your application at: ${styleText('underline', `${conf.GOTO_URL}/${app.id}`)}`,
+  );
+  Logger.println('');
+}
+
+function shellCommand(command) {
+  return `${styleText('grey', '$')} ${styleText('yellow', command)}`;
+}
+
+function printFieldsAsTable(indent, fields) {
+  const fieldsWithValues = Object.fromEntries(Object.entries(fields).filter(([_, value]) => typeof value === 'string'));
+  const labelMaxWidth = Math.max(...Object.keys(fieldsWithValues).map((label) => label.length));
+  return Object.entries(fieldsWithValues).forEach(([label, value]) => {
+    Logger.println(`${' '.repeat(indent)}${label.padEnd(labelMaxWidth, ' ')}  ${styleText('grey', value)}`);
+  });
+}
+
+export const createCommand = defineCommand({
+  description: 'Create an application',
+  since: '0.2.0',
+  options: {
+    type: defineOption({
+      name: 'type',
+      schema: z.string(),
+      description: 'Instance type',
+      aliases: ['t'],
+      placeholder: 'instance-type',
+      complete: listAvailableTypes,
+    }),
+    region: defineOption({
+      name: 'region',
+      schema: z.string().default('par'),
+      description: `Region, can be ${AVAILABLE_ZONES.map((name) => `'${name}'`).join(', ')}`,
+      aliases: ['r'],
+      placeholder: 'zone',
+      complete: listAvailableZones,
+    }),
+    github: defineOption({
+      name: 'github',
+      schema: z.string().optional(),
+      description: 'GitHub application to use for deployments',
+      placeholder: 'owner/repo',
+    }),
+    task: defineOption({
+      name: 'task',
+      schema: z.string().min(1).optional(),
+      description: 'The application launch as a task executing the given command, then stopped',
+      aliases: ['T'],
+      placeholder: 'command',
+    }),
+    org: orgaIdOrNameOption,
+    alias: aliasCreationOption,
+    format: humanJsonOutputFormatOption,
+  },
+  args: [
+    defineArgument({
+      schema: z.string().optional(),
+      description: 'Application name (current directory name is used if not specified)',
+      placeholder: 'app-name',
+    }),
+  ],
+  async handler(options, rawName) {
+    const { type: typeName } = options;
+
+    const { org: orgaIdOrName, alias, region, github: githubOwnerRepo, format, task: taskCommand } = 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, isTask, envVars);
+    await AppConfig.addLinkedApplication(app, alias);
+
+    switch (format) {
+      case 'json': {
+        Logger.printJson({
+          id: app.id,
+          name: app.name,
+          executedAs: app.instance.lifetime,
+          env: app.env,
+          deployUrl: app.deployUrl,
+        });
+        break;
+      }
+
+      case 'human':
+      default:
+        await displayAppCreation(app, alias, github, taskCommand);
+    }
+  },
+});

package/src/commands/create/create.docs.md

@@ -0,0 +1,27 @@
+# 📖 `clever create` command reference
+
+## ➡️ `clever create` <kbd>Since 0.2.0</kbd>
+
+Create an application
+
+```bash
+clever create --type <instance-type> [<app-name>] [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`app-name`|Application name (current directory name is used if not specified) *(optional)*|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-t`, `--type` `<instance-type>`|Instance type **(required)**|
+|`-a`, `--alias` `<alias>`|Short name for the application|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+|`--github` `<owner/repo>`|GitHub application to use for deployments|
+|`-o`, `--org`, `--owner` `<org-id\|org-name>`|Organisation to target by its ID (or name, if unambiguous)|
+|`-r`, `--region` `<zone>`|Region, can be 'par', 'parhds', 'grahds', 'rbx', 'rbxhds', 'scw', 'ldn', 'mtl', 'sgp', 'syd', 'wsw' (default: par)|
+|`-T`, `--task` `<command>`|The application launch as a task executing the given command, then stopped|

package/src/commands/{curl.js → curl/curl.command.js}

@@ -1,9 +1,10 @@
 import { addOauthHeader } from '@clevercloud/client/esm/oauth.js';
 import dedent from 'dedent';
 import { spawn } from 'node:child_process';
-import { styleText } from '../lib/style-text.js';
-import { Logger } from '../logger.js';
-import { conf, loadOAuthConf } from '../models/configuration.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import { conf, loadOAuthConf } from '../../models/configuration.js';
 
 async function loadTokens() {
   const tokens = await loadOAuthConf();
@@ -69,3 +70,9 @@ export async function curl() {
 
   spawn('curl', curlArgs, { stdio: 'inherit' });
 }
+
+export const curlCommand = defineCommand({
+  description: "Query Clever Cloud's API using Clever Tools credentials",
+  since: '2.10.0',
+  handler: null,
+});

package/src/commands/curl/curl.docs.md

@@ -0,0 +1,9 @@
+# 📖 `clever curl` command reference
+
+## ➡️ `clever curl` <kbd>Since 2.10.0</kbd>
+
+Query Clever Cloud's API using Clever Tools credentials
+
+```bash
+clever curl
+```

package/src/commands/database/database.args.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { defineArgument } from '../../lib/define-argument.js';
+
+export const databaseIdArg = defineArgument({
+  schema: z.string(),
+  description: 'Any database ID (format: addon_UUID, postgresql_UUID, mysql_UUID, ...)',
+  placeholder: 'database-id|addon-id',
+});

package/src/commands/database/database.backups.command.js

@@ -0,0 +1,60 @@
+import { getBackups } from '@clevercloud/client/esm/api/v2/backups.js';
+import { formatTable } from '../../format-table.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { Logger } from '../../logger.js';
+import { findOwnerId } from '../../models/addon.js';
+import { resolveAddonId, resolveRealId } from '../../models/ids-resolver.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { humanJsonOutputFormatOption, orgaIdOrNameOption } from '../global.options.js';
+import { databaseIdArg } from './database.args.js';
+
+export const databaseBackupsCommand = defineCommand({
+  description: 'List available database backups',
+  since: '2.10.0',
+  options: {
+    org: orgaIdOrNameOption,
+    format: humanJsonOutputFormatOption,
+  },
+  args: [databaseIdArg],
+  async handler(options, addonIdOrRealId) {
+    const { org, format } = options;
+
+    const realId = await resolveRealId(addonIdOrRealId);
+    const addonId = await resolveAddonId(addonIdOrRealId);
+    const ownerId = await findOwnerId(org, realId);
+
+    const backups = await getBackups({ ownerId, ref: realId }).then(sendToApi);
+
+    if (backups.length === 0 && format === 'human') {
+      Logger.println('There are no backups yet');
+      return;
+    }
+
+    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'];
+
+        Logger.println(formatTable([head, ...formattedLines]));
+      }
+    }
+  },
+});

package/src/commands/database/database.backups.download.command.js

@@ -0,0 +1,55 @@
+import { getBackups } from '@clevercloud/client/esm/api/v2/backups.js';
+import fs from 'node:fs';
+import { Writable } from 'node:stream';
+import { z } from 'zod';
+import { defineArgument } from '../../lib/define-argument.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { defineOption } from '../../lib/define-option.js';
+import { findOwnerId } from '../../models/addon.js';
+import { resolveRealId } from '../../models/ids-resolver.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { orgaIdOrNameOption } from '../global.options.js';
+import { databaseIdArg } from './database.args.js';
+
+export const databaseBackupsDownloadCommand = defineCommand({
+  description: 'Download a database backup',
+  since: '2.10.0',
+  options: {
+    output: defineOption({
+      name: 'output',
+      schema: z.string().optional(),
+      description: 'Redirect the output of the command in a file',
+      aliases: ['out'],
+      placeholder: 'file-path',
+    }),
+    org: orgaIdOrNameOption,
+  },
+  args: [
+    databaseIdArg,
+    defineArgument({
+      schema: z.string(),
+      description: 'A Database backup ID (format: UUID)',
+      placeholder: 'backup-id',
+    }),
+  ],
+  async handler(options, addonIdOrRealId, backupId) {
+    const { org, output } = options;
+
+    const addonId = await resolveRealId(addonIdOrRealId);
+    const ownerId = await findOwnerId(org, addonId);
+
+    const backups = await getBackups({ ownerId, ref: addonId }).then(sendToApi);
+    const backup = backups.find((backup) => backup.backup_id === backupId);
+
+    if (backup == null) {
+      throw new Error('no backup with this ID');
+    }
+
+    const response = await globalThis.fetch(backup.download_url);
+    if (!response.ok) {
+      throw new Error('Failed to download backup');
+    }
+
+    await response.body.pipeTo(Writable.toWeb(output ? fs.createWriteStream(output) : process.stdout));
+  },
+});

package/src/commands/database/database.command.js

@@ -0,0 +1,10 @@
+import { defineCommand } from '../../lib/define-command.js';
+
+export const databaseCommand = defineCommand({
+  description: 'Manage databases and backups',
+  since: '2.10.0',
+  options: {},
+  args: [],
+  // Parent command - no handler, only contains subcommands
+  handler: null,
+});

package/src/commands/database/database.docs.md

@@ -0,0 +1,52 @@
+# 📖 `clever database` command reference
+
+## ➡️ `clever database` <kbd>Since 2.10.0</kbd>
+
+Manage databases and backups
+
+```bash
+clever database
+```
+
+## ➡️ `clever database backups` <kbd>Since 2.10.0</kbd>
+
+List available database backups
+
+```bash
+clever database backups <database-id|addon-id> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`database-id|addon-id`|Any database ID (format: addon_UUID, postgresql_UUID, mysql_UUID, ...)|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+|`-o`, `--org`, `--owner` `<org-id\|org-name>`|Organisation to target by its ID (or name, if unambiguous)|
+
+## ➡️ `clever database backups download` <kbd>Since 2.10.0</kbd>
+
+Download a database backup
+
+```bash
+clever database backups download <database-id|addon-id> <backup-id> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`database-id|addon-id`|Any database ID (format: addon_UUID, postgresql_UUID, mysql_UUID, ...)|
+|`backup-id`|A Database backup ID (format: UUID)|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-o`, `--org`, `--owner` `<org-id\|org-name>`|Organisation to target by its ID (or name, if unambiguous)|
+|`--output`, `--out` `<file-path>`|Redirect the output of the command in a file|

package/src/commands/delete/delete.command.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+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 AppConfig from '../../models/app_configuration.js';
+import * as Application from '../../models/application.js';
+import { aliasOption, appIdOrNameOption } from '../global.options.js';
+
+export const deleteCommand = defineCommand({
+  description: 'Delete an application',
+  since: '0.7.0',
+  options: {
+    yes: defineOption({
+      name: 'yes',
+      schema: z.boolean().default(false),
+      description: 'Skip confirmation and delete the application directly',
+      aliases: ['y'],
+    }),
+    alias: aliasOption,
+    app: appIdOrNameOption,
+  },
+  args: [],
+  async handler(options) {
+    const { alias, app: appIdOrName, yes: skipConfirmation } = options;
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+
+    const app = await Application.get(ownerId, appId);
+    if (app == null) {
+      throw new Error("The application doesn't exist");
+    }
+
+    // delete app
+    await Application.deleteApp(app, skipConfirmation);
+    Logger.printSuccess(`Application ${styleText('green', styleText('bold', `${app.name}`))} successfully deleted!`);
+    Logger.println(`  ${styleText('grey', '•')} Application ID: ${styleText('grey', app.id)}`);
+
+    const wasUnlinked = await AppConfig.removeLinkedApplication({ appId, alias });
+    if (wasUnlinked) {
+      Logger.println(`  ${styleText('blue', '→')} Local alias ${styleText('blue', alias || app.name)} unlinked`);
+    }
+  },
+});

package/src/commands/delete/delete.docs.md

@@ -0,0 +1,17 @@
+# 📖 `clever delete` command reference
+
+## ➡️ `clever delete` <kbd>Since 0.7.0</kbd>
+
+Delete an application
+
+```bash
+clever delete [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-a`, `--alias` `<alias>`|Short name for the application|
+|`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`-y`, `--yes`|Skip confirmation and delete the application directly|

package/src/commands/deploy/deploy.command.js

@@ -0,0 +1,166 @@
+import { getAllDeployments } from '@clevercloud/client/esm/api/v2/application.js';
+import dedent from 'dedent';
+import { z } from 'zod';
+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 AppConfig from '../../models/app_configuration.js';
+import * as Application from '../../models/application.js';
+import * as ExitStrategy from '../../models/exit-strategy-option.js';
+import * as git from '../../models/git.js';
+import { completeBranches } from '../../models/git.js';
+import * as Log from '../../models/log-v4.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { aliasOption, exitOnDeployOption, followDeployLogsOption, quietOption } from '../global.options.js';
+
+async function restartOnSameCommit(ownerId, appId, commitIdToPush, quiet, withoutCache, exitStrategy) {
+  const cacheSuffix = withoutCache ? ' without using cache' : '';
+  Logger.println(`🔄 Restarting ${styleText('bold', appId)}${cacheSuffix} ${styleText('grey', `(${commitIdToPush})`)}`);
+
+  const restart = await Application.redeploy(ownerId, appId, commitIdToPush, withoutCache);
+  return Log.watchDeploymentAndDisplayLogs({ ownerId, appId, deploymentId: restart.deploymentId, quiet, exitStrategy });
+}
+
+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);
+  }
+}
+
+export const deployCommand = defineCommand({
+  description: 'Deploy an application',
+  since: '0.2.0',
+  options: {
+    branch: defineOption({
+      name: 'branch',
+      schema: z.string().default(''),
+      description: 'Branch to push (current branch by default)',
+      aliases: ['b'],
+      placeholder: 'branch',
+      complete: completeBranches,
+    }),
+    tag: defineOption({
+      name: 'tag',
+      schema: z.string().default(''),
+      description: 'Tag to push (none by default)',
+      aliases: ['t'],
+      placeholder: 'tag',
+    }),
+    force: defineOption({
+      name: 'force',
+      schema: z.boolean().default(false),
+      description: "Force deploy even if it's not fast-forwardable",
+      aliases: ['f'],
+    }),
+    sameCommitPolicy: defineOption({
+      name: 'same-commit-policy',
+      schema: z.enum(['error', 'ignore', 'restart', 'rebuild']).default('error'),
+      description: 'What to do when local and remote commit are identical (error, ignore, restart, rebuild)',
+      aliases: ['p'],
+      placeholder: 'policy',
+    }),
+    alias: aliasOption,
+    quiet: quietOption,
+    follow: followDeployLogsOption,
+    exitOnDeploy: exitOnDeployOption,
+  },
+  args: [],
+  async handler(options) {
+    const { alias, branch: branchName, tag: tagName, quiet, force, follow, sameCommitPolicy, exitOnDeploy } = options;
+
+    const exitStrategy = ExitStrategy.get(follow, exitOnDeploy);
+
+    const appData = await AppConfig.getAppDetails({ alias });
+    const { ownerId, appId } = appData;
+
+    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).then(({ commitId }) => commitId);
+
+    await git.addRemote(appData.alias, appData.deployUrl);
+
+    if (commitIdToPush === remoteHeadCommitId) {
+      switch (sameCommitPolicy) {
+        case 'ignore':
+          Logger.printSuccess(`The application is up-to-date (${styleText('grey', remoteHeadCommitId)})`);
+          return;
+        case 'restart':
+          return restartOnSameCommit(ownerId, appId, commitIdToPush, quiet, false, exitStrategy);
+        case 'rebuild':
+          return restartOnSameCommit(ownerId, appId, commitIdToPush, quiet, true, exitStrategy);
+        case 'error':
+        default: {
+          const restartCommand =
+            commitIdToPush !== deployedCommitId ? `clever restart --commit ${commitIdToPush}` : 'clever restart';
+          throw new Error(dedent`
+              Remote HEAD has the same commit as the one to push ${styleText('grey', `(${remoteHeadCommitId})`)}, your application is up-to-date.
+              Create a new commit, use ${styleText('blue', restartCommand)} or the ${styleText('blue', '--same-commit-policy')} option.
+            `);
+        }
+      }
+    }
+
+    // It's sometimes tricky to figure out the deployment ID for the current git push.
+    // We on have the commit ID but there in a situation where the last deployment was cancelled, it may have the same commit ID.
+    // So before pushing, we get the last deployments so we can after the push figure out which deployment is new…
+    const knownDeployments = await getAllDeployments({ id: ownerId, appId, limit: 5 }).then(sendToApi);
+
+    Logger.println(dedent`
+        ${styleText('bold', `🚀 Deploying ${styleText('green', appData.name)}`)}
+           Application ID  ${styleText('grey', `${appId}`)}
+           Organisation ID ${styleText('grey', `${ownerId}`)}
+      `);
+
+    Logger.println();
+
+    Logger.println(styleText('bold', '🔀 Git information'));
+    if (remoteHeadCommitId == null || deployedCommitId == null) {
+      Logger.println(`   ${styleText('yellow', '!')} App is brand new, no commits on remote yet`);
+    } else {
+      Logger.println(`   Remote head     ${styleText('yellow', remoteHeadCommitId)} (${branchRefspec})`);
+      Logger.println(`   Deployed commit ${styleText('yellow', deployedCommitId)}`);
+    }
+    Logger.println(
+      `   Local commit    ${styleText('yellow', commitIdToPush)} ${styleText('blue', '[will be deployed]')}`,
+    );
+
+    Logger.println();
+
+    Logger.println(dedent`
+        ${styleText('bold', '🔄 Deployment progress')}
+           ${styleText('blue', '→ Pushing source code to Clever Cloud…')}
+      `);
+
+    await git.push(appData.deployUrl, commitIdToPush, force).catch(async (e) => {
+      const isShallow = await git.isShallow();
+      if (isShallow) {
+        throw new Error(
+          'Failed to push your source code because your repository is shallow and therefore cannot be pushed to the Clever Cloud remote.',
+        );
+      } else {
+        throw e;
+      }
+    });
+
+    await Logger.println(`   ${styleText('green', '✓ Code pushed to Clever Cloud')}`);
+
+    return Log.watchDeploymentAndDisplayLogs({
+      ownerId,
+      appId,
+      commitId: commitIdToPush,
+      knownDeployments,
+      quiet,
+      exitStrategy,
+    });
+  },
+});

package/src/commands/deploy/deploy.docs.md

@@ -0,0 +1,22 @@
+# 📖 `clever deploy` command reference
+
+## ➡️ `clever deploy` <kbd>Since 0.2.0</kbd>
+
+Deploy an application
+
+```bash
+clever deploy [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-a`, `--alias` `<alias>`|Short name for the application|
+|`-b`, `--branch` `<branch>`|Branch to push (current branch by default)|
+|`-e`, `--exit-on` `<step>`|Step at which the logs streaming is ended, steps are: deploy-start, deploy-end, never (default: deploy-end)|
+|`--follow`|Continue to follow logs after deployment has ended *(deprecated, use `--exit-on never` instead)*|
+|`-f`, `--force`|Force deploy even if it's not fast-forwardable|
+|`-q`, `--quiet`|Don't show logs during deployment|
+|`-p`, `--same-commit-policy` `<policy>`|What to do when local and remote commit are identical (error, ignore, restart, rebuild) (default: error)|
+|`-t`, `--tag` `<tag>`|Tag to push (none by default)|