neonctl 1.16.5 → 1.17.1

package/README.md

@@ -1,37 +1,15 @@
-Neon offers several methods for working with your projects. Utilizing the Neon Command Line Interface (CLI), you can operate Neon directly from a terminal or via automation. The Neon CLI facilitates numerous functions, such as Neon authentication, project creation and management, and more.
+The Neon CLI supports numerous operations, such as authentication and management of Neon projects, branches, compute endpoints, databases, roles, and more.
 
-## Synopsis
-
-The `neonctl` command can be called from command line. Without any arguments, it displays command usage and help:
-
-```bash
-usage: neonctl <cmd> [args]
-
-Commands:
-  neonctl auth                Authenticate
-  neonctl projects [command]  Manage projects
-  neonctl me                  Show current user
-  neonctl branches            Manage branches
-
-Options:
-      --version     Show version number                                [boolean]
-      --help        Show help                                          [boolean]
-  -o, --output      Set output format
-                  [string] [choices: "json", "yaml", "table"] [default: "table"]
-      --api-host    The API host   [default: "https://console.neon.tech/api/v2"]
-      --config-dir  Path to config directory
-                              [string] [default: "/home/eduard/.config/neonctl"]
-      --oauth-host  URL to Neon OAUTH host [default: "https://oauth2.neon.tech"]
-      --client-id   OAuth client id                [string] [default: "neonctl"]
-      --api-key     API key                               [string] [default: ""]
-```
+The Neon CLI command name is `neonctl`. The GitHub repository for the Neon CLI is found [here](https://github.com/neondatabase/neonctl).
 
 ## Install the Neon CLI
 
-This topic describes how to install the `neonctl` command-line interface tool and connect to Neon.
+This section describes how to install the Neon CLI.
 
 ### Prerequisites
 
+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
@@ -44,83 +22,114 @@ This topic describes how to install the `neonctl` command-line interface tool an
    npm -v
    ```
 
-If you need to install either `Node.js` or `npm`, refer to instructions on [official nodejs page](https://nodejs.org) or you can use [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
 
-To download and install Neon CLI, run the following command:
+To install the Neon CLI, run the following command:
 
 ```shell
 npm i -g neonctl
 ```
 
-### Connect
+### Upgrade
 
-To authenticate to Neon, run the following command:
+To upgrade to the latest version of the Neon CLI, run the `npm i -g neonctl` command again.
 
-```shell
+## Connect
+
+Run the following command to authenticate a connection to Neon:
+
+```bash
 neonctl auth
 ```
 
-The command launches a browser window where you can authorize the Neon CLI to access your Neon account. After granting permission, your credentials are saved locally to a credentials file.
+The `auth` command launches a browser window where you can authorize the Neon CLI to access your Neon account. Running a Neon CLI command without authenticating with [neonctl auth](https://neon.tech/docs/reference/cli-auth) automatically launches the browser authentication process.
 
-## Commands
+Alternatively, you can authenticate a connection with a Neon API key using the `--api-key` option when running a Neon CLI command. For example, an API key is used with the following `neonctl projects list` command:
 
-### neonctl auth
+```bash
+neonctl projects list --api-key <neon_api_key>
+```
 
-Authenticates the user or caller to Neon. See [Connect](#connect).
+For information about obtaining an Neon API key, see [Authentication](https://api-docs.neon.tech/reference/authentication), in the _Neon API Reference_.
 
-### neonctl me
+## Configure autocompletion
 
-Returns information about the authenticated user.
+The Neon CLI supports autocompletion, which you can configure in a few easy steps. See [Neon CLI commands — completion](https://neon.tech/docs/reference/cli-completion) for instructions.
 
-```bash
-$> neonctl me
-┌────────────────┬──────────────────────────┬────────────┬────────────────┐
-│ Login          │ Email                    │ Name       │ Projects Limit │
-├────────────────┼──────────────────────────┼────────────┼────────────────┤
-│ user1          │ user1@example.com        │ User1      │ 1              │
-└────────────────┴──────────────────────────┴────────────┴────────────────┘
-```
+## 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     |
+
+## Global options
 
+Global options are supported with any Neon CLI command.
 
-### neonctl projects
+| 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| -                                 |
 
-For creating and managing Neon projects.
+- <a id="output"></a>`-o, --output`
 
-## neonctl branches
-For creating and managing Neon branches.
+  Sets the output format. Supported options are `json`, `yaml`, and `table`. The default is `table`. Table output may be limited. The `json` and `yaml` output formats show all data.
 
-## Options
+  ```bash
+  neonctl me --output json
+  ```
 
-### version
+- <a id="config-dir"></a>`--config-dir`
 
-Shows the neonctl version number
+  Specifies the path to the `neonctl` configuration directory. To view the default configuration directory containing you `credentials.json` file, run `neonctl --help`. The credentials file is created when you authenticate using the `neonctl auth` command. This option is only necessary if you move your `neonctl` configuration file to a location other than the default.
 
-### help
+  ```bash
+  neonctl projects list --config-dir /home/dtprice/.config/neonctl
+  ```
 
-Shows the neonctl command-line help
+- <a id="api-key"></a>`--api-key`
 
-### output, o
+  Specifies your Neon API key. You can authenticate using a Neon API key when running a Neon CLI command instead of using `neonctl auth`. For information about obtaining an Neon API key, see [Authentication](https://api-docs.neon.tech/reference/authentication), in the _Neon API Reference_.
 
-Sets the output format.
+  ```bash
+  neonctl <command> --api-key <neon_api_key>
+  ```
 
-### api-host
+- <a id="analytics"></a>`--analytics`
 
-Shows the API host
+  Analytics are enabled by default to gather information about the CLI commands and options that are used by our customers. This data collection assists in offering support, and allows for a better understanding of typical usage patterns so that we can improve user experience. Neon does not collect user-defined data, such as project IDs or command payloads. To opt-out of analytics data collection, specify `--no-analytics` or `--analytics false`.
 
-### config-dir
+- <a id="version"></a>`-v, --version`
 
-Sets the path to the `neonctl` configuration directory
+  Shows the Neon CLI version number.
 
-### oauth-host
+  ```bash
+  $ neonctl --version
+  1.15.0
+  ```
 
-Sets the URL of Neon OAuth host
+- <a id="help"></a>`-h, --help`
 
-### client-id
+  Shows the `neonctl` command-line help. You can view help for `neonctl`, a `neonctl` command, or a `neonctl` subcommand, as shown in the following examples:
 
-Sets the OAuth client id
+  ```bash
+  neonctl --help
 
-### api-key
+  neonctl branches --help
 
-Sets the API key
+  neonctl branches create --help
+  ```

package/commands/branches.js

@@ -33,19 +33,29 @@ export const builder = (argv) => argv
         describe: 'Parent branch name or id or timestamp or LSN. Defaults to the primary branch',
         type: 'string',
     },
-    endpoint: {
-        describe: 'Create a branch with or without an endpoint. By default branch is created with a read-write endpoint. To create a branch without endpoint use --no-endpoint',
+    compute: {
+        describe: 'Create a branch with or without a compute. By default branch is created with a read-write compute. To create a branch without compute use --no-compute',
         type: 'boolean',
         default: true,
     },
-    readonly: {
-        describe: 'Create a read-only branch',
-        type: 'boolean',
-        implies: 'endpoint',
+    type: {
+        describe: 'Type of compute to add',
+        type: 'string',
+        implies: 'compute',
+        default: EndpointType.ReadWrite,
+        choices: Object.values(EndpointType),
     },
 }), 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))
+    .command('add-compute <id|name>', 'Add a compute to a branch', (yargs) => yargs.options({
+    type: {
+        type: 'string',
+        choices: Object.values(EndpointType),
+        describe: 'Type of compute to add',
+        default: EndpointType.ReadOnly,
+    },
+}), 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));
 export const handler = (args) => {
@@ -94,12 +104,10 @@ const create = async (props) => {
             name: props.name,
             ...parentProps,
         },
-        endpoints: props.endpoint
+        endpoints: props.compute
             ? [
                 {
-                    type: props.readonly
-                        ? EndpointType.ReadOnly
-                        : EndpointType.ReadWrite,
+                    type: props.type,
                 },
             ]
             : [],
@@ -155,3 +163,15 @@ const get = async (props) => {
         fields: BRANCH_FIELDS,
     });
 };
+const addCompute = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { data } = await retryOnLock(() => props.apiClient.createProjectEndpoint(props.projectId, {
+        endpoint: {
+            branch_id: branchId,
+            type: props.type,
+        },
+    }));
+    writer(props).end(data.endpoint, {
+        fields: ['id', 'host'],
+    });
+};

package/commands/branches.test.js

@@ -31,7 +31,8 @@ describe('branches', () => {
             'test',
             '--name',
             'test_branch',
-            '--readonly',
+            '--type',
+            'read_only',
         ],
         expected: {
             snapshot: true,
@@ -46,7 +47,7 @@ describe('branches', () => {
             'test',
             '--name',
             'test_branch',
-            '--no-endpoint',
+            '--no-compute',
         ],
         expected: {
             snapshot: true,
@@ -154,4 +155,11 @@ describe('branches', () => {
             snapshot: true,
         },
     });
+    testCliCommand({
+        name: 'add compute',
+        args: ['branches', 'add-compute', 'test_branch', '--project-id', 'test'],
+        expected: {
+            snapshot: true,
+        },
+    });
 });

package/commands/connection_string.js

@@ -63,7 +63,7 @@ export const handler = async (props) => {
             if (data.roles.length === 1) {
                 return data.roles[0].name;
             }
-            throw new Error(`Multiple roles found for the branch, please provide one with the --role.name option: ${data.roles
+            throw new Error(`Multiple roles found for the branch, please provide one with the --role-name option: ${data.roles
                 .map((r) => r.name)
                 .join(', ')}`);
         }));
@@ -77,7 +77,7 @@ export const handler = async (props) => {
             if (data.databases.length === 1) {
                 return data.databases[0].name;
             }
-            throw new Error(`Multiple databases found for the branch, please provide one with the --database.name option: ${data.databases
+            throw new Error(`Multiple databases found for the branch, please provide one with the --database-name option: ${data.databases
                 .map((d) => d.name)
                 .join(', ')}`);
         }));

package/config.js

@@ -2,9 +2,9 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { existsSync, mkdirSync } from 'node:fs';
 import { isCi } from './env.js';
-export const defaultDir = join(homedir(), process.env.XDG_CONFIG_HOME || '.config', 'neonctl');
+export const defaultDir = join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'neonctl');
 export const ensureConfigDir = async ({ 'config-dir': configDir, }) => {
     if (!existsSync(configDir) && !isCi()) {
-        mkdirSync(configDir);
+        mkdirSync(configDir, { recursive: true });
     }
 };

package/package.json

@@ -5,7 +5,7 @@
     "url": "git@github.com:neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "1.16.5",
+  "version": "1.17.1",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",

package/writer.js

@@ -48,17 +48,18 @@ export const writer = (props) => {
             }
             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: config.fields.map((field) => field
+                    head: fields.map((field) => field
                         .split('_')
                         .map((word) => word[0].toUpperCase() + word.slice(1))
                         .join(' ')),
                 });
                 arrayData.forEach((item) => {
-                    table.push(config.fields.map((field) => item[field] ?? ''));
+                    table.push(fields.map((field) => item[field]));
                 });
                 if (config.title) {
                     out.write((isCi() ? config.title : chalk.bold(config.title)) + '\n');