neonctl 1.25.3 → 1.25.5

package/README.md

@@ -1,40 +1,44 @@
-The Neon CLI supports numerous operations, such as authentication and management of Neon projects, branches, compute endpoints, databases, roles, and more.
-
-The Neon CLI command name is `neonctl`. The GitHub repository for the Neon CLI is found [here](https://github.com/neondatabase/neonctl).
+The Neon CLI is a command-line interface that lets you manage [Neon Serverless Postgres](https://neon.tech/) directly from the terminal. For the complete documentation, see [Neon CLI](https://neon.tech/docs/reference/neon-cli).
 
 ## Install the Neon CLI
 
-This section describes how to install the Neon CLI.
+**npm**
 
-### Prerequisites
+```shell
+npm i -g neonctl
+```
 
-Before installing, ensure that you have met the following prerequisites:
+Requires Node.js 18.0 or higher.
 
-- Node.js 16.0 or higher. To check if you already have Node.js, run the following command:
+**Howebrew**
 
-  ```shell
-  node -v
-  ```
+```shell
+brew install neonctl
+```
 
-- The `npm` package manager. To check if you already have `npm`, run the following command:
+**Binary (macOS, Linux, Windows)**
 
-  ```shell
-  npm -v
-  ```
+Download a binary file [here](https://github.com/neondatabase/neonctl/releases).
 
-  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).
+### Upgrade
+
+**npm**
 
-### Install
+```shell
+npm update -g neonctl
+```
 
-To install the Neon CLI, run the following command:
+Requires Node.js 18.0 or higher.
+
+**Howebrew**
 
 ```shell
-npm i -g neonctl
+brew upgrade neonctl
 ```
 
-### Upgrade
+**Binary (macOS, Linux, Windows)**
 
-To upgrade to the latest version of the Neon CLI, run the `npm i -g neonctl` command again.
+To upgrade a binary version, download the latest binary file, as described above, and replace your old binary with the new one.
 
 ## Connect
 
@@ -70,6 +74,7 @@ The Neon CLI supports autocompletion, which you can configure in a few easy step
 | [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        |
+| [set-context](https://neon.tech/reference/cli-set-context)             |                                                                           | Set context for session      |
 | [completion](https://neon.tech/reference/cli-completion)               |                                                                           | Generate a completion script |
 
 ## Global options
@@ -136,7 +141,7 @@ Global options are supported with any Neon CLI command.
 
 ## Contribute
 
-To run the CLI locally execute build command after making changes:
+To run the CLI locally, execute the build command after making changes:
 
 ```shell
 npm run build
@@ -148,7 +153,7 @@ To develop continuously:
 npm run watch
 ```
 
-To run commands from the local build replace the `neonctl` command with `node dist`, for example:
+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

@@ -9,7 +9,9 @@ import { CREDENTIALS_FILE } from '../config.js';
 export const command = 'auth';
 export const aliases = ['login'];
 export const describe = 'Authenticate';
-export const builder = (yargs) => yargs;
+export const builder = (yargs) => yargs.option('context-file', {
+    hidden: true,
+});
 export const handler = async (args) => {
     await authFlow(args);
 };

package/commands/index.js

@@ -1,5 +1,6 @@
 import * as auth from './auth.js';
 import * as projects from './projects.js';
+import * as ipAllow from './ip_allow.js';
 import * as users from './user.js';
 import * as branches from './branches.js';
 import * as databases from './databases.js';
@@ -11,6 +12,7 @@ export default [
     auth,
     users,
     projects,
+    ipAllow,
     branches,
     databases,
     roles,

package/commands/ip_allow.js

@@ -0,0 +1,135 @@
+import { writer } from '../writer.js';
+import { projectUpdateRequest } from '../parameters.gen.js';
+import { log } from '../log.js';
+const IP_ALLOW_FIELDS = [
+    'id',
+    'name',
+    'IP_addresses',
+    'primary_branch_only',
+];
+export const command = 'ip-allow';
+export const describe = 'Manage IP Allow';
+export const builder = (argv) => {
+    return argv
+        .usage('$0 ip-allow <sub-command> [options]')
+        .options({
+        'project-id': {
+            describe: 'Project ID',
+            type: 'string',
+        },
+    })
+        .command('list', 'List the IP allowlist', (yargs) => yargs, async (args) => {
+        await list(args);
+    })
+        .command('add [ips...]', 'Add IP addresses to the IP allowlist', (yargs) => yargs
+        .usage('$0 ip-allow add [ips...]')
+        .positional('ips', {
+        describe: 'The list of IP addresses to add',
+        type: 'string',
+        default: [],
+        array: true,
+    })
+        .options({
+        'primary-only': {
+            describe: projectUpdateRequest['project.settings.allowed_ips.primary_branch_only'].description,
+            type: 'boolean',
+        },
+    }), async (args) => {
+        await add(args);
+    })
+        .command('remove [ips...]', 'Remove IP addresses from the IP allowlist', (yargs) => yargs.usage('$0 ip-allow remove [ips...]').positional('ips', {
+        describe: 'The list of IP addresses to remove',
+        type: 'string',
+        default: [],
+        array: true,
+    }), async (args) => {
+        await remove(args);
+    })
+        .command('reset [ips...]', 'Reset the IP allowlist', (yargs) => yargs.usage('$0 ip-allow remove [ips...]').positional('ips', {
+        describe: 'The list of IP addresses to reset',
+        type: 'string',
+        default: [],
+        array: true,
+    }), async (args) => {
+        await reset(args);
+    });
+};
+export const handler = (args) => {
+    return args;
+};
+const list = async (props) => {
+    const { data } = await props.apiClient.getProject(props.projectId);
+    writer(props).end(parse(data.project), {
+        fields: IP_ALLOW_FIELDS,
+    });
+};
+const add = async (props) => {
+    if (props.ips.length <= 0) {
+        log.error(`Enter individual IP addresses, define ranges with a dash, or use CIDR notation for more flexibility.
+       Example: neonctl ip-allow add 192.168.1.1, 192.168.1.20-192.168.1.50, 192.168.1.0/24 --project-id <id>`);
+        return;
+    }
+    const project = {};
+    const { data } = await props.apiClient.getProject(props.projectId);
+    const existingAllowedIps = data.project.settings?.allowed_ips;
+    project.settings = {
+        allowed_ips: {
+            ips: [...new Set(props.ips.concat(existingAllowedIps?.ips ?? []))],
+            primary_branch_only: props.primaryOnly ?? existingAllowedIps?.primary_branch_only ?? false,
+        },
+    };
+    const { data: response } = await props.apiClient.updateProject(props.projectId, {
+        project,
+    });
+    writer(props).end(parse(response.project), {
+        fields: IP_ALLOW_FIELDS,
+    });
+};
+const remove = async (props) => {
+    if (props.ips.length <= 0) {
+        log.error(`Remove individual IP addresses and ranges. Example: neonctl ip-allow remove 192.168.1.1 --project-id <id>`);
+        return;
+    }
+    const project = {};
+    const { data } = await props.apiClient.getProject(props.projectId);
+    const existingAllowedIps = data.project.settings?.allowed_ips;
+    project.settings = {
+        allowed_ips: {
+            ips: existingAllowedIps?.ips.filter((ip) => !props.ips.includes(ip)) ?? [],
+            primary_branch_only: existingAllowedIps?.primary_branch_only ?? false,
+        },
+    };
+    const { data: response } = await props.apiClient.updateProject(props.projectId, {
+        project,
+    });
+    writer(props).end(parse(response.project), {
+        fields: IP_ALLOW_FIELDS,
+    });
+};
+const reset = async (props) => {
+    const project = {};
+    project.settings = {
+        allowed_ips: {
+            ips: props.ips,
+            primary_branch_only: false,
+        },
+    };
+    const { data } = await props.apiClient.updateProject(props.projectId, {
+        project,
+    });
+    writer(props).end(parse(data.project), {
+        fields: IP_ALLOW_FIELDS,
+    });
+    if (props.ips.length <= 0) {
+        log.info(`The IP allowlist has been reset. All databases on project "${data.project.name}" are now exposed to the internet`);
+    }
+};
+const parse = (project) => {
+    const ips = project.settings?.allowed_ips?.ips ?? [];
+    return {
+        id: project.id,
+        name: project.name,
+        IP_addresses: ips,
+        primary_branch_only: project.settings?.allowed_ips?.primary_branch_only ?? false,
+    };
+};

package/commands/ip_allow.test.js

@@ -0,0 +1,71 @@
+import { describe } from '@jest/globals';
+import { testCliCommand } from '../test_utils/test_cli_command.js';
+describe('ip-allow', () => {
+    testCliCommand({
+        name: 'list IP allow',
+        args: ['ip-allow', 'list', '--project-id', 'test'],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'Add IP allow - Error',
+        args: ['ip-allow', 'add', '--projectId', 'test'],
+        expected: {
+            stderr: `ERROR: Enter individual IP addresses, define ranges with a dash, or use CIDR notation for more flexibility.
+       Example: neonctl ip-allow add 192.168.1.1, 192.168.1.20-192.168.1.50, 192.168.1.0/24 --project-id <id>
+`,
+        },
+    });
+    testCliCommand({
+        name: 'Add IP allow',
+        args: [
+            'ip-allow',
+            'add',
+            '127.0.0.1',
+            '192.168.10.1-192.168.10.15',
+            '--primary-only',
+            '--project-id',
+            'test',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'Remove IP allow - Error',
+        args: ['ip-allow', 'remove', '--project-id', 'test'],
+        expected: {
+            stderr: `ERROR: Remove individual IP addresses and ranges. Example: neonctl ip-allow remove 192.168.1.1 --project-id <id>
+`,
+        },
+    });
+    testCliCommand({
+        name: 'Remove IP allow',
+        args: ['ip-allow', 'remove', '192.168.1.1', '--project-id', 'test'],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'Reset IP allow',
+        args: ['ip-allow', 'reset', '--project-id', 'test'],
+        expected: {
+            snapshot: true,
+            stdout: `id: test
+name: test_project
+IP_addresses: []
+primary_branch_only: false
+`,
+            stderr: `INFO: The IP allowlist has been reset. All databases on project "test_project" are now exposed to the internet
+`,
+        },
+    });
+    testCliCommand({
+        name: 'Reset IP allow to new list',
+        args: ['ip-allow', 'reset', '192.168.2.2', '--project-id', 'test'],
+        expected: {
+            snapshot: true,
+        },
+    });
+});

package/commands/projects.js

@@ -54,10 +54,12 @@ export const builder = (argv) => {
                 .description,
             type: 'string',
             array: true,
+            deprecated: "Deprecated. Use 'ip-allow' command",
         },
         'ip-primary-only': {
             describe: projectUpdateRequest['project.settings.allowed_ips.primary_branch_only'].description,
             type: 'boolean',
+            deprecated: "Deprecated. Use 'ip-allow' command",
         },
     }), async (args) => {
         await update(args);

package/commands/user.js

@@ -1,7 +1,9 @@
 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.option('context-file', {
+    hidden: true,
+});
 export const handler = async (args) => {
     await me(args);
 };

package/index.js

@@ -128,6 +128,7 @@ builder = builder
     .alias('version', 'v')
     .completion()
     .scriptName(basename(process.argv[1]) === 'neon' ? 'neon' : 'neonctl')
+    .epilog('For more information, visit https://neon.tech/docs/reference/neon-cli')
     .fail(async (msg, err) => {
     if (process.argv.some((arg) => arg === '--help' || arg === '-h')) {
         await showHelp(builder);

package/package.json

@@ -5,7 +5,7 @@
     "url": "git@github.com:neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "1.25.3",
+  "version": "1.25.5",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",
@@ -90,6 +90,7 @@
     "clean": "rm -rf dist",
     "generateParams": "node --loader ts-node/esm ./generateOptionsFromSpec.ts",
     "start": "node src/index.js",
+    "pretest": "npm run build",
     "test": "node --experimental-vm-modules node_modules/.bin/jest",
     "prepare": "test -d .git && husky install || true"
   },

package/utils/string.js

@@ -2,3 +2,4 @@ export const toSnakeCase = (str) => str
     .split(' ')
     .map((word) => word.toLowerCase())
     .join('_');
+export const isObject = (value) => value != null && value === Object(value);

package/writer.js

@@ -2,7 +2,53 @@ import YAML from 'yaml';
 import Table from 'cli-table';
 import chalk from 'chalk';
 import { isCi } from './env.js';
-import { toSnakeCase } from './utils/string.js';
+import { isObject, toSnakeCase } from './utils/string.js';
+const writeYaml = (chunks) => {
+    return YAML.stringify(chunks.length === 1
+        ? chunks[0].data
+        : Object.fromEntries(chunks.map(({ config, data }, idx) => [
+            config.title ? toSnakeCase(config.title) : idx,
+            data,
+        ])), null, 2);
+};
+const writeJson = (chunks) => {
+    return JSON.stringify(chunks.length === 1
+        ? chunks[0].data
+        : Object.fromEntries(chunks.map(({ config, data }, idx) => [
+            config.title ? toSnakeCase(config.title) : idx,
+            data,
+        ])), null, 2);
+};
+const writeTable = (chunks, out) => {
+    chunks.forEach(({ data, config }) => {
+        const arrayData = Array.isArray(data) ? data : [data];
+        const fields = config.fields.filter((field) => arrayData.some((item) => item[field] !== undefined && item[field] !== ''));
+        const table = new Table({
+            style: {
+                head: ['green'],
+            },
+            head: fields.map((field) => field
+                .split('_')
+                .map((word) => word[0].toUpperCase() + word.slice(1))
+                .join(' ')),
+        });
+        arrayData.forEach((item) => {
+            table.push(fields.map((field) => {
+                const value = item[field];
+                return Array.isArray(value)
+                    ? value.join('\n')
+                    : isObject(value)
+                        ? JSON.stringify(value, null, 2)
+                        : value;
+            }));
+        });
+        if (config.title) {
+            out.write((isCi() ? config.title : chalk.bold(config.title)) + '\n');
+        }
+        out.write(table.toString());
+        out.write('\n');
+    });
+};
 /**
  *
  * Parses the output format, takes data and writes the output to stdout.
@@ -30,44 +76,12 @@ export const writer = (props) => {
                 chunks.push({ data: args[0], config: args[1] });
             }
             if (props.output == 'yaml') {
-                out.write(YAML.stringify(chunks.length === 1
-                    ? chunks[0].data
-                    : Object.fromEntries(chunks.map(({ config, data }, idx) => [
-                        config.title ? toSnakeCase(config.title) : idx,
-                        data,
-                    ])), null, 2));
-                return;
+                return out.write(writeYaml(chunks));
             }
             if (props.output == 'json') {
-                out.write(JSON.stringify(chunks.length === 1
-                    ? chunks[0].data
-                    : Object.fromEntries(chunks.map(({ config, data }, idx) => [
-                        config.title ? toSnakeCase(config.title) : idx,
-                        data,
-                    ])), null, 2));
-                return;
+                return out.write(writeJson(chunks));
             }
-            chunks.forEach(({ data, config }) => {
-                const arrayData = Array.isArray(data) ? data : [data];
-                const fields = config.fields.filter((field) => arrayData.some((item) => item[field] !== undefined && item[field] !== ''));
-                const table = new Table({
-                    style: {
-                        head: ['green'],
-                    },
-                    head: fields.map((field) => field
-                        .split('_')
-                        .map((word) => word[0].toUpperCase() + word.slice(1))
-                        .join(' ')),
-                });
-                arrayData.forEach((item) => {
-                    table.push(fields.map((field) => item[field]));
-                });
-                if (config.title) {
-                    out.write((isCi() ? config.title : chalk.bold(config.title)) + '\n');
-                }
-                out.write(table.toString());
-                out.write('\n');
-            });
+            return writeTable(chunks, out);
         },
     };
 };