neonctl 1.19.1 → 1.21.0

package/README.md

@@ -12,17 +12,17 @@ Before installing, ensure that you have met the following prerequisites:
 
 - Node.js 16.0 or higher. To check if you already have Node.js, run the following command:
 
-    ```shell
-    node -v
-    ```
+  ```shell
+  node -v
+  ```
 
-- The `npm` package manager.  To check if you already have `npm`, run the following command:
+- The `npm` package manager. To check if you already have `npm`, run the following command:
 
-   ```shell
-   npm -v
-   ```
+  ```shell
+  npm -v
+  ```
 
-  If you need to install  `Node.js` or `npm`, refer to instructions on the [official nodejs page](https://nodejs.org) or use the [Node version manager](https://github.com/nvm-sh/nvm).
+  If you need to install `Node.js` or `npm`, refer to instructions on the [official nodejs page](https://nodejs.org) or use the [Node version manager](https://github.com/nvm-sh/nvm).
 
 ### Install
 
@@ -60,30 +60,30 @@ The Neon CLI supports autocompletion, which you can configure in a few easy step
 
 ## Commands
 
-| Command                                                 | Subcommands                            | Description               |
-|---------------------------------------------------------|----------------------------------------|---------------------------|
-| [auth](https://neon.tech/docs/reference/cli-auth)                                     |                                        | Authenticate              |
-| [projects](https://neon.tech/docs/reference/cli-projects)                             | `list`, `create`, `update`, `delete`, `get` | Manage projects           |
-| [me](../reference/cli-me)                                         |                                        | Show current user         |
-| [branches](https://neon.tech/docs/reference/cli-branches)                             | `list`, `create`, `rename`, `add-compute`, `set-primary`, `delete`, `get` | Manage branches           |
-| [databases](https://neon.tech/docs/reference/cli-databases)                           | `list`, `create`, `delete`             | Manage databases          |
-| [roles](https://neon.tech/docs/reference/cli-roles)                                   | `list`, `create`,  `delete`            | Manage roles              |
-| [operations](https://neon.tech/reference/cli-operations)                         | `list`                                 | Manage operations         |
-| [connection-string](https://neon.tech/reference/cli-connection-string)           |                                        | Get connection string     |
-| [completion](https://neon.tech/reference/cli-completion)           |                                        | Generate a completion script     |
+| Command                                                                | Subcommands                                                               | Description                  |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------- |
+| [auth](https://neon.tech/docs/reference/cli-auth)                      |                                                                           | Authenticate                 |
+| [projects](https://neon.tech/docs/reference/cli-projects)              | `list`, `create`, `update`, `delete`, `get`                               | Manage projects              |
+| [me](../reference/cli-me)                                              |                                                                           | Show current user            |
+| [branches](https://neon.tech/docs/reference/cli-branches)              | `list`, `create`, `rename`, `add-compute`, `set-primary`, `delete`, `get` | Manage branches              |
+| [databases](https://neon.tech/docs/reference/cli-databases)            | `list`, `create`, `delete`                                                | Manage databases             |
+| [roles](https://neon.tech/docs/reference/cli-roles)                    | `list`, `create`, `delete`                                                | Manage roles                 |
+| [operations](https://neon.tech/reference/cli-operations)               | `list`                                                                    | Manage operations            |
+| [connection-string](https://neon.tech/reference/cli-connection-string) |                                                                           | Get connection string        |
+| [completion](https://neon.tech/reference/cli-completion)               |                                                                           | Generate a completion script |
 
 ## Global options
 
 Global options are supported with any Neon CLI command.
 
-| Option      | Description                         | Type   | Default                           |
-| :---------  | :---------------------------------- | :----- | :-------------------------------- |
-| [-o, --output](#output)| Set the Neon CLI output format (`json`, `yaml`, or `table`)                 | string | table                           |
-| [--config-dir](#config-dir)| Path to the Neon CLI configuration directory            | string | `/home/<user>/.config/neonctl`   |
-| [--api-key](#api-key)   | Neon API key                             | string | ""                                |
-| [--analytics](#analytics) | Manage analytics                    | boolean| true                              |
-| [-v, --version](#version)   | Show the Neon CLI version number                 | boolean| -                                 |
-| [-h, --help](#help)      | Show the Neon CLI help                           | boolean| -                                 |
+| Option                      | Description                                                 | Type    | Default                        |
+| :-------------------------- | :---------------------------------------------------------- | :------ | :----------------------------- |
+| [-o, --output](#output)     | Set the Neon CLI output format (`json`, `yaml`, or `table`) | string  | table                          |
+| [--config-dir](#config-dir) | Path to the Neon CLI configuration directory                | string  | `/home/<user>/.config/neonctl` |
+| [--api-key](#api-key)       | Neon API key                                                | string  | ""                             |
+| [--analytics](#analytics)   | Manage analytics                                            | boolean | true                           |
+| [-v, --version](#version)   | Show the Neon CLI version number                            | boolean | -                              |
+| [-h, --help](#help)         | Show the Neon CLI help                                      | boolean | -                              |
 
 - <a id="output"></a>`-o, --output`
 
@@ -133,3 +133,23 @@ Global options are supported with any Neon CLI command.
 
   neonctl branches create --help
   ```
+
+## Contribute
+
+To run the CLI locally execute build command after making changes:
+
+```shell
+npm run build
+```
+
+To develop continuously:
+
+```shell
+npm run watch
+```
+
+To run commands from the local build replace the `neonctl` command with `node dist`, for example:
+
+```shell
+node dist branches --help
+```

package/commands/auth.js

@@ -6,10 +6,11 @@ import { log } from '../log.js';
 import { getApiClient } from '../api.js';
 import { isCi } from '../env.js';
 import { CREDENTIALS_FILE } from '../config.js';
+import { showHelpMiddleware } from '../help.js';
 export const command = 'auth';
 export const aliases = ['login'];
 export const describe = 'Authenticate';
-export const builder = (yargs) => yargs;
+export const builder = (yargs) => yargs.middleware(showHelpMiddleware(yargs, true));
 export const handler = async (args) => {
     await authFlow(args);
 };

package/commands/branches.js

@@ -1,10 +1,11 @@
 import { EndpointType } from '@neondatabase/api-client';
 import { writer } from '../writer.js';
-import { branchCreateRequest } from '../parameters.gen.js';
-import { commandFailHandler } from '../utils/middlewares.js';
+import { branchCreateRequest, branchCreateRequestEndpointOptions, } from '../parameters.gen.js';
 import { retryOnLock } from '../api.js';
 import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
 import { looksLikeBranchId, looksLikeLSN, looksLikeTimestamp, } from '../utils/formats.js';
+import { showHelpMiddleware } from '../help.js';
+import { psql } from '../utils/psql.js';
 const BRANCH_FIELDS = [
     'id',
     'name',
@@ -16,9 +17,7 @@ export const command = 'branches';
 export const describe = 'Manage branches';
 export const aliases = ['branch'];
 export const builder = (argv) => argv
-    .demandCommand(1, '')
-    .fail(commandFailHandler)
-    .usage('usage: $0 branches <sub-command> [options]')
+    .usage('$0 branches <sub-command> [options]')
     .options({
     'project-id': {
         describe: 'Project ID',
@@ -45,6 +44,18 @@ export const builder = (argv) => argv
         default: EndpointType.ReadWrite,
         choices: Object.values(EndpointType),
     },
+    'suspend-timeout': {
+        describe: branchCreateRequestEndpointOptions.suspend_timeout_seconds
+            .description,
+        type: 'number',
+        implies: 'compute',
+        default: 0,
+    },
+    psql: {
+        type: 'boolean',
+        describe: 'Connect to a new branch via psql',
+        default: false,
+    },
 }), async (args) => await create(args))
     .command('rename <id|name> <new-name>', 'Rename a branch', (yargs) => yargs, async (args) => await rename(args))
     .command('set-primary <id|name>', 'Set a branch as primary', (yargs) => yargs, async (args) => await setPrimary(args))
@@ -57,7 +68,8 @@ export const builder = (argv) => argv
     },
 }), async (args) => await addCompute(args))
     .command('delete <id|name>', 'Delete a branch', (yargs) => yargs, async (args) => await deleteBranch(args))
-    .command('get <id|name>', 'Get a branch', (yargs) => yargs, async (args) => await get(args));
+    .command('get <id|name>', 'Get a branch', (yargs) => yargs, async (args) => await get(args))
+    .middleware(showHelpMiddleware(argv), true);
 export const handler = (args) => {
     return args;
 };
@@ -108,6 +120,7 @@ const create = async (props) => {
             ? [
                 {
                     type: props.type,
+                    suspend_timeout_seconds: props.suspendTimeout,
                 },
             ]
             : [],
@@ -130,6 +143,14 @@ const create = async (props) => {
         });
     }
     out.end();
+    if (props.psql) {
+        if (!data.connection_uris || !data.connection_uris?.length) {
+            throw new Error(`Branch ${data.branch.id} doesn't have a connection uri`);
+        }
+        const connection_uri = data.connection_uris[0].connection_uri;
+        const psqlArgs = props['--'];
+        await psql(connection_uri, psqlArgs);
+    }
 };
 const rename = async (props) => {
     const branchId = await branchIdFromProps(props);

package/commands/branches.test.js

@@ -22,6 +22,39 @@ describe('branches', () => {
             snapshot: true,
         },
     });
+    testCliCommand({
+        name: 'create branch and connect with psql',
+        args: [
+            'branches',
+            'create',
+            '--project-id',
+            'test',
+            '--name',
+            'test_branch',
+            '--psql',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'create branch and connect with psql and psql args',
+        args: [
+            'branches',
+            'create',
+            '--project-id',
+            'test',
+            '--name',
+            'test_branch',
+            '--psql',
+            '--',
+            '-c',
+            'SELECT 1',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
     testCliCommand({
         name: 'create with readonly endpoint',
         args: [
@@ -101,6 +134,22 @@ describe('branches', () => {
             snapshot: true,
         },
     });
+    testCliCommand({
+        name: 'create with suspend timeout',
+        args: [
+            'branches',
+            'create',
+            '--project-id',
+            'test',
+            '--name',
+            'test_branch_with_suspend_timeout',
+            '--suspend-timeout',
+            '60',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
     testCliCommand({
         name: 'delete by id',
         args: [
@@ -176,7 +225,13 @@ describe('branches', () => {
     });
     testCliCommand({
         name: 'get by id',
-        args: ['branches', 'get', 'br-cloudy-branch-12345678', '--project-id', 'test'],
+        args: [
+            'branches',
+            'get',
+            'br-cloudy-branch-12345678',
+            '--project-id',
+            'test',
+        ],
         expected: {
             snapshot: true,
         },

package/commands/connection_string.js

@@ -1,11 +1,15 @@
 import { EndpointType } from '@neondatabase/api-client';
 import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
+import { showHelpMiddleware } from '../help.js';
+import { writer } from '../writer.js';
+import { psql } from '../utils/psql.js';
 export const command = 'connection-string [branch]';
 export const aliases = ['cs'];
 export const describe = 'Get connection string';
 export const builder = (argv) => {
     return argv
-        .usage('usage: $0 connection-string [branch] [options]')
+        .usage('$0 connection-string [branch] [options]')
+        .middleware(showHelpMiddleware(argv, true))
         .positional('branch', {
         describe: 'Branch name or id. If ommited will use the primary branch',
         type: 'string',
@@ -38,6 +42,15 @@ export const builder = (argv) => {
             choices: Object.values(EndpointType),
             describe: 'Endpoint type',
         },
+        extended: {
+            type: 'boolean',
+            describe: 'Show extended information',
+        },
+        psql: {
+            type: 'boolean',
+            describe: 'Connect to a database via psql using connection string',
+            default: false,
+        },
     })
         .middleware(fillSingleProject);
 };
@@ -81,14 +94,14 @@ export const handler = async (props) => {
                 .map((d) => d.name)
                 .join(', ')}`);
         }));
-    const { data: password } = await props.apiClient.getProjectBranchRolePassword(props.projectId, endpoint.branch_id, role);
+    const { data: { password }, } = await props.apiClient.getProjectBranchRolePassword(props.projectId, endpoint.branch_id, role);
     const host = props.pooled
         ? endpoint.host.replace(endpoint.id, `${endpoint.id}-pooler`)
         : endpoint.host;
     const connectionString = new URL(`postgres://${host}`);
     connectionString.pathname = database;
     connectionString.username = role;
-    connectionString.password = password.password;
+    connectionString.password = password;
     if (props.prisma) {
         connectionString.searchParams.set('connect_timeout', '30');
         if (props.pooled) {
@@ -96,5 +109,21 @@ export const handler = async (props) => {
             connectionString.searchParams.set('pgbouncer', 'true');
         }
     }
-    process.stdout.write(connectionString.toString() + '\n');
+    if (props.psql) {
+        const psqlArgs = props['--'];
+        await psql(connectionString.toString(), psqlArgs);
+    }
+    else if (props.extended) {
+        writer(props).end({
+            connection_string: connectionString.toString(),
+            host,
+            role,
+            password,
+            database,
+            options: connectionString.searchParams.toString(),
+        }, { fields: ['host', 'role', 'password', 'database'] });
+    }
+    else {
+        process.stdout.write(connectionString.toString() + '\n');
+    }
 };

package/commands/connection_string.test.js

@@ -34,7 +34,7 @@ describe('connection_string', () => {
         },
     });
     testCliCommand({
-        name: 'connection_string branch id',
+        name: 'connection_string branch id 8 digits',
         args: [
             'connection-string',
             'br-cloudy-branch-12345678',
@@ -66,40 +66,6 @@ describe('connection_string', () => {
             snapshot: true,
         },
     });
-    testCliCommand({
-        name: 'connection_string pooled branch id',
-        args: [
-            'connection-string',
-            'br-sunny-branch-123456',
-            '--project-id',
-            'test',
-            '--database-name',
-            'test_db',
-            '--role-name',
-            'test_role',
-            '--pooled',
-        ],
-        expected: {
-            snapshot: true,
-        },
-    });
-    testCliCommand({
-        name: 'connection_string pooled branch id',
-        args: [
-            'connection-string',
-            'br-cloudy-branch-12345678',
-            '--project-id',
-            'test',
-            '--database-name',
-            'test_db',
-            '--role-name',
-            'test_role',
-            '--pooled',
-        ],
-        expected: {
-            snapshot: true,
-        },
-    });
     testCliCommand({
         name: 'connection_string prisma',
         args: [
@@ -118,16 +84,17 @@ describe('connection_string', () => {
         },
     });
     testCliCommand({
-        name: 'connection_string pooled branch id',
+        name: 'connection_string prisma pooled',
         args: [
             'connection-string',
-            'br-sunny-branch-123456',
+            'test_branch',
             '--project-id',
             'test',
             '--database-name',
             'test_db',
             '--role-name',
             'test_role',
+            '--prisma',
             '--pooled',
         ],
         expected: {
@@ -135,82 +102,67 @@ describe('connection_string', () => {
         },
     });
     testCliCommand({
-        name: 'connection_string pooled branch id',
+        name: 'connection_string prisma pooled extended',
         args: [
             'connection-string',
-            'br-cloudy-branch-12345678',
+            'test_branch',
             '--project-id',
             'test',
             '--database-name',
             'test_db',
             '--role-name',
             'test_role',
+            '--prisma',
             '--pooled',
+            '--extended',
         ],
         expected: {
             snapshot: true,
         },
     });
     testCliCommand({
-        name: 'connection_string prisma pooled',
-        args: [
-            'connection-string',
-            'test_branch',
-            '--project-id',
-            'test',
-            '--database-name',
-            'test_db',
-            '--role-name',
-            'test_role',
-            '--prisma',
-            '--pooled',
-        ],
+        name: 'connection_string without any args should pass',
+        args: ['connection-string'],
+        mockDir: 'single_project',
         expected: {
             snapshot: true,
         },
     });
     testCliCommand({
-        name: 'connection_string prisma pooled branch id',
+        name: 'connection_string with psql',
         args: [
             'connection-string',
-            'br-sunny-branch-123456',
+            'test_branch',
             '--project-id',
             'test',
             '--database-name',
             'test_db',
             '--role-name',
             'test_role',
-            '--prisma',
-            '--pooled',
+            '--psql',
         ],
         expected: {
             snapshot: true,
         },
     });
     testCliCommand({
-        name: 'connection_string prisma pooled branch id',
+        name: 'connection_string with psql and psql args',
         args: [
             'connection-string',
-            'br-cloudy-branch-12345678',
+            'test_branch',
             '--project-id',
             'test',
             '--database-name',
             'test_db',
             '--role-name',
             'test_role',
-            '--prisma',
-            '--pooled',
+            '--psql',
+            '--',
+            '-c',
+            'SELECT 1',
         ],
         expected: {
             snapshot: true,
         },
     });
-    testCliCommand({
-        name: 'connection_string without any args should pass',
-        args: ['connection-string'],
-        mockDir: 'single_project',
-        expected: {
-            snapshot: true,
-        },
-    });
 });

package/commands/databases.js

@@ -1,15 +1,14 @@
 import { retryOnLock } from '../api.js';
 import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
-import { commandFailHandler } from '../utils/middlewares.js';
 import { writer } from '../writer.js';
+import { showHelpMiddleware } from '../help.js';
 const DATABASE_FIELDS = ['name', 'owner_name', 'created_at'];
 export const command = 'databases';
 export const describe = 'Manage databases';
 export const aliases = ['database', 'db'];
 export const builder = (argv) => argv
-    .demandCommand(1, '')
-    .fail(commandFailHandler)
-    .usage('usage: $0 databases <sub-command> [options]')
+    .usage('$0 databases <sub-command> [options]')
+    .middleware(showHelpMiddleware(argv))
     .options({
     'project-id': {
         describe: 'Project ID',

package/commands/help.test.js

@@ -1,11 +1,12 @@
 import { describe, expect } from '@jest/globals';
+import chalk from 'chalk';
 import { testCliCommand } from '../test_utils/test_cli_command.js';
 describe('help', () => {
     testCliCommand({
         name: 'without args',
         args: [],
         expected: {
-            stderr: expect.stringContaining('usage: neonctl <command> [options]'),
+            stderr: expect.stringContaining(`neonctl <command> ${chalk.green('[options]')}`),
         },
     });
 });

package/commands/operations.js

@@ -1,14 +1,13 @@
 import { fillSingleProject } from '../utils/enrichers.js';
-import { commandFailHandler } from '../utils/middlewares.js';
 import { writer } from '../writer.js';
+import { showHelpMiddleware } from '../help.js';
 const OPERATIONS_FIELDS = ['id', 'action', 'status', 'created_at'];
 export const command = 'operations';
 export const describe = 'Manage operations';
 export const aliases = ['operation'];
 export const builder = (argv) => argv
-    .demandCommand(1, '')
-    .fail(commandFailHandler)
-    .usage('usage: $0 operations <sub-command> [options]')
+    .usage('$0 operations <sub-command> [options]')
+    .middleware(showHelpMiddleware(argv))
     .options({
     'project-id': {
         describe: 'Project ID',

package/commands/projects.js

@@ -1,7 +1,8 @@
+import { showHelpMiddleware } from '../help.js';
 import { log } from '../log.js';
 import { projectCreateRequest } from '../parameters.gen.js';
-import { commandFailHandler } from '../utils/middlewares.js';
 import { writer } from '../writer.js';
+import { psql } from '../utils/psql.js';
 const PROJECT_FIELDS = ['id', 'name', 'region_id', 'created_at'];
 const REGIONS = [
     'aws-us-west-2',
@@ -16,9 +17,8 @@ export const describe = 'Manage projects';
 export const aliases = ['project'];
 export const builder = (argv) => {
     return argv
-        .demandCommand(1, '')
-        .fail(commandFailHandler)
-        .usage('usage: $0 projects <sub-command> [options]')
+        .usage('$0 projects <sub-command> [options]')
+        .middleware(showHelpMiddleware(argv))
         .command('list', 'List projects', (yargs) => yargs, async (args) => {
         await list(args);
     })
@@ -31,6 +31,11 @@ export const builder = (argv) => {
             describe: `The region ID. Possible values: ${REGIONS.join(', ')}`,
             type: 'string',
         },
+        psql: {
+            type: 'boolean',
+            describe: 'Connect to a new project via psql',
+            default: false,
+        },
     }), async (args) => {
         await create(args);
     })
@@ -88,6 +93,11 @@ const create = async (props) => {
         title: 'Connection URIs',
     });
     out.end();
+    if (props.psql) {
+        const connection_uri = data.connection_uris[0].connection_uri;
+        const psqlArgs = props['--'];
+        await psql(connection_uri, psqlArgs);
+    }
 };
 const deleteProject = async (props) => {
     const { data } = await props.apiClient.deleteProject(props.id);

package/commands/projects.test.js

@@ -15,6 +15,20 @@ describe('projects', () => {
             snapshot: true,
         },
     });
+    testCliCommand({
+        name: 'create and connect with psql',
+        args: ['projects', 'create', '--name', 'test_project', '--psql'],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'create and connect with psql and psql args',
+        args: ['projects', 'create', '--name', 'test_project', '--psql', '--', '-c', 'SELECT 1'],
+        expected: {
+            snapshot: true,
+        },
+    });
     testCliCommand({
         name: 'delete',
         args: ['projects', 'delete', 'test'],

package/commands/roles.js

@@ -1,15 +1,14 @@
 import { retryOnLock } from '../api.js';
 import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
-import { commandFailHandler } from '../utils/middlewares.js';
 import { writer } from '../writer.js';
+import { showHelpMiddleware } from '../help.js';
 const ROLES_FIELDS = ['name', 'created_at'];
 export const command = 'roles';
 export const describe = 'Manage roles';
 export const aliases = ['role'];
 export const builder = (argv) => argv
-    .demandCommand(1, '')
-    .fail(commandFailHandler)
-    .usage('usage: $0 roles <sub-command> [options]')
+    .middleware(showHelpMiddleware(argv))
+    .usage('$0 roles <sub-command> [options]')
     .options({
     'project-id': {
         describe: 'Project ID',

package/commands/user.js

@@ -1,7 +1,8 @@
+import { showHelpMiddleware } from '../help.js';
 import { writer } from '../writer.js';
 export const command = 'me';
 export const describe = 'Show current user';
-export const builder = (yargs) => yargs;
+export const builder = (yargs) => yargs.middleware(showHelpMiddleware(yargs, true));
 export const handler = async (args) => {
     await me(args);
 };

package/errors.js

@@ -3,6 +3,9 @@ const ERROR_MATCHERS = [
     [/^Missing required argument: (.*)$/, 'MISSING_ARGUMENT'],
 ];
 export const matchErrorCode = (message) => {
+    if (!message) {
+        return 'UNKNOWN_ERROR';
+    }
     for (const [matcher, code] of ERROR_MATCHERS) {
         const match = message.match(matcher);
         if (match) {

package/help.js

@@ -0,0 +1,119 @@
+import cliui from 'cliui';
+import chalk from 'chalk';
+import { consumeBlockIfMatches, consumeNextMatching, drawPointer, splitColumns, } from './utils/ui.js';
+// target width for the leftmost column
+const SPACE_WIDTH = 20;
+const formatHelp = (help) => {
+    const lines = help.split('\n');
+    const result = [];
+    // full command, like `neonctl projects list`
+    const topLevelCommand = consumeNextMatching(lines, /^.*/);
+    if (topLevelCommand) {
+        result.push(chalk.bold(topLevelCommand.replace('[options]', chalk.reset.green('[options]'))));
+        result.push('');
+    }
+    // commands description block
+    // example command to see: neonctl projects
+    const commandsBlock = consumeBlockIfMatches(lines, /^Commands:/);
+    if (commandsBlock.length > 0) {
+        const header = commandsBlock.shift();
+        result.push(header);
+        const ui = cliui({
+            width: 0,
+        });
+        commandsBlock.forEach((line) => {
+            const [command, description] = splitColumns(line);
+            ui.div(chalk.cyan(command));
+            ui.div({
+                text: chalk.gray(drawPointer(SPACE_WIDTH)),
+                width: SPACE_WIDTH,
+                padding: [0, 0, 0, 0],
+            }, { text: description, padding: [0, 0, 0, 2] });
+        });
+        result.push(ui.toString());
+        result.push('');
+    }
+    // positional args block
+    // example command to see: neonctl branches rename
+    const positionalsBlock = consumeBlockIfMatches(lines, /Positionals:/);
+    if (positionalsBlock.length > 0) {
+        const header = positionalsBlock.shift();
+        result.push(header);
+        const ui = cliui({
+            width: 0,
+        });
+        positionalsBlock.forEach((line) => {
+            const [positional, description] = splitColumns(line);
+            ui.div({
+                text: positional,
+                width: SPACE_WIDTH,
+                padding: [0, 2, 0, 0],
+            }, {
+                text: description,
+                padding: [0, 0, 0, 0],
+            });
+        });
+        result.push(ui.toString());
+        result.push('');
+    }
+    // command description
+    // example command to see: neonctl projects list
+    const descritpionBlock = consumeBlockIfMatches(lines, /^(?!.*options:)/i);
+    if (descritpionBlock.length > 0) {
+        result.push(descritpionBlock.shift());
+        result.push('');
+    }
+    while (true) {
+        // there are two options blocks: global and specific
+        // example to see both: neonctl projects create
+        const optionsBlock = consumeBlockIfMatches(lines, /.*options:/i);
+        if (optionsBlock.length === 0) {
+            break;
+        }
+        result.push(optionsBlock.shift());
+        optionsBlock.forEach((line) => {
+            const [option, description] = splitColumns(line);
+            const ui = cliui({
+                width: 0,
+            });
+            if (option.startsWith('-')) {
+                ui.div({
+                    text: chalk.green(option),
+                    padding: [0, 0, 0, 0],
+                });
+                ui.div({
+                    text: chalk.gray(drawPointer(SPACE_WIDTH)),
+                    width: SPACE_WIDTH,
+                    padding: [0, 2, 0, 0],
+                }, {
+                    text: chalk.rgb(210, 210, 210)(description ?? ''),
+                    padding: [0, 0, 0, 0],
+                });
+            }
+            else {
+                ui.div({
+                    padding: [0, 0, 0, 0],
+                    text: '',
+                    width: SPACE_WIDTH,
+                }, {
+                    text: chalk.rgb(210, 210, 210)(option),
+                    padding: [0, 0, 0, 0],
+                });
+            }
+            result.push(ui.toString());
+        });
+        result.push('');
+    }
+    return [...result, ...lines];
+};
+export const showHelp = async (argv) => {
+    // add wrap to ensure that there are no line breaks
+    const help = await argv.wrap(500).getHelp();
+    process.stderr.write(formatHelp(help).join('\n') + '\n');
+    process.exit(0);
+};
+export const showHelpMiddleware = (argv, ignoreSubCmdPresence) => async (args) => {
+    if ((!ignoreSubCmdPresence && args._.length === 1) || args.help) {
+        await showHelp(argv);
+    }
+};

package/index.js

@@ -24,10 +24,14 @@ import { analyticsMiddleware, sendError } from './analytics.js';
 import { isCi } from './env.js';
 import { isAxiosError } from 'axios';
 import { matchErrorCode } from './errors.js';
+import { showHelp } from './help.js';
 let builder = yargs(hideBin(process.argv));
 builder = builder
     .scriptName(pkg.name)
-    .usage('usage: $0 <command> [options]')
+    .usage('$0 <command> [options]')
+    .parserConfiguration({
+    'populate--': true,
+})
     .help()
     .option('output', {
     alias: 'o',
@@ -92,11 +96,21 @@ builder = builder
     .middleware(analyticsMiddleware, true)
     .group('version', 'Global options:')
     .alias('version', 'v')
+    .help(false)
     .group('help', 'Global options:')
+    .option('help', {
+    describe: 'Show help',
+    type: 'boolean',
+    default: false,
+})
     .alias('help', 'h')
     .completion()
     .scriptName(basename(process.argv[1]) === 'neon' ? 'neon' : 'neonctl')
     .fail(async (msg, err) => {
+    if (process.argv.some((arg) => arg === '--help' || arg === '-h')) {
+        await showHelp(builder);
+        process.exit(0);
+    }
     if (isAxiosError(err)) {
         if (err.code === 'ECONNABORTED') {
             log.error('Request timed out');
@@ -121,8 +135,8 @@ builder = builder
 });
 (async () => {
     const args = await builder.argv;
-    if (args._.length === 0) {
-        builder.showHelp();
+    if (args._.length === 0 || args.help) {
+        await showHelp(builder);
         process.exit(0);
     }
 })();

package/package.json

@@ -5,7 +5,7 @@
     "url": "git@github.com:neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "1.19.1",
+  "version": "1.21.0",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",
@@ -32,6 +32,7 @@
     "@types/express": "^4.17.17",
     "@types/inquirer": "^9.0.3",
     "@types/node": "^18.7.13",
+    "@types/which": "^3.0.0",
     "@types/yargs": "^17.0.24",
     "@typescript-eslint/eslint-plugin": "^5.34.0",
     "@typescript-eslint/parser": "^5.34.0",
@@ -60,6 +61,7 @@
     "inquirer": "^9.2.6",
     "open": "^8.4.0",
     "openid-client": "^5.1.9",
+    "which": "^3.0.1",
     "yaml": "^2.1.1",
     "yargs": "^17.7.2"
   },

package/test_utils/test_cli_command.js

@@ -29,6 +29,9 @@ export const testCliCommand = ({ args, name, expected, mockDir = 'main', }) => {
                 ...args,
             ], {
                 stdio: 'pipe',
+                env: {
+                    PATH: `mocks/bin:${process.env.PATH}`,
+                },
             });
             return new Promise((resolve, reject) => {
                 cp.stdout?.on('data', (data) => {

package/utils/middlewares.js

@@ -1,5 +1,3 @@
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
 /**
  * This middleware is needed to fill in the args for nested objects,
  * so that required arguments would work
@@ -20,10 +18,3 @@ export const fillInArgs = (args, currentArgs = args, acc = []) => {
         }
     });
 };
-export const commandFailHandler = async (_msg, _err, yyargs) => {
-    const argv = yargs(hideBin(process.argv));
-    if (argv.argv._.length === 1) {
-        yyargs.showHelp();
-        process.exit(1);
-    }
-};

package/utils/psql.js

@@ -0,0 +1,17 @@
+import { log } from '../log.js';
+import { spawn } from 'child_process';
+import which from 'which';
+export const psql = async (connection_uri, args = []) => {
+    const psqlPathOrNull = await which('psql', { nothrow: true });
+    if (psqlPathOrNull === null) {
+        log.error(`psql is not available in the PATH`);
+        process.exit(1);
+    }
+    log.info('Connecting to the database using psql...');
+    const psql = spawn(psqlPathOrNull, [connection_uri, ...args], {
+        stdio: 'inherit',
+    });
+    psql.on('exit', (code) => {
+        process.exit(code === null ? 1 : code);
+    });
+};

package/utils/ui.js

@@ -0,0 +1,52 @@
+// returns the next string if matches the given matcher,
+// otherwise returns null
+// consumes the line from the lines array
+export const consumeNextMatching = (lines, matcher) => {
+    while (lines.length > 0) {
+        const line = lines.shift().trim();
+        if (line === '') {
+            continue;
+        }
+        if (matcher.test(line)) {
+            return line;
+        }
+        return null;
+    }
+    return null;
+};
+// returns strings if next non-empty line matches the given matcher,
+// otherwise returns empty array
+// consumes the lines from the lines array
+export const consumeBlockIfMatches = (lines, matcher) => {
+    const result = [];
+    if (lines.length === 0) {
+        return result;
+    }
+    let line = lines.shift();
+    while (line.trim() === '') {
+        line = lines.shift();
+    }
+    if (!matcher.test(line)) {
+        lines.unshift(line);
+        return result;
+    }
+    result.push(line);
+    while (lines.length > 0) {
+        line = lines.shift();
+        if (line.trim() === '') {
+            break;
+        }
+        result.push(line);
+    }
+    return result;
+};
+export const splitColumns = (line) => line.trim().split(/\s{2,}/);
+export const drawPointer = (width) => {
+    const result = [];
+    result.push('└');
+    for (let i = 0; i < width - 4; i++) {
+        result.push('─');
+    }
+    result.push('>');
+    return result.join('');
+};