{
  "tool": "neonctl",
  "name": "Neon CLI",
  "long_name": "Neon CLI (neonctl, neon)",
  "aliases": [
    "neon",
    "neon-cli",
    "neondatabase-cli",
    "neon-pkgs",
    "neonctl-cli"
  ],
  "homepage": "https://neon.com/docs/reference/cli",
  "url": "https://insidetheloop.dev/tools/neonctl",
  "markdown_url": "https://insidetheloop.dev/tools/neonctl.md",
  "date_modified": "2026-10-10T11:41:00Z",
  "title": "Neon CLI 8.3.5: latest version, login command, deploy flags and gotchas",
  "description": "Neon CLI 8.3.5 (2026-10-09 UTC): login/auth rename, deploy confirmations, Postgres-only config, default neondb_owner, and reproduced errors.",
  "answer": "The latest Neon CLI (`neonctl`, alias `neon`) is 8.3.5, released 2026-10-09 16:44 UTC. Upgrade with `npm i -g neonctl@latest` or `npm i -g neon@latest`. From 8.0.11 to 8.3.5, the help tree adds `neon login` and removes `neon auth`; `auth` remains its alias. The release line also adds `-y`/`--yes` confirmation aliases for `deploy` and `config apply`, replaces `--services none` with `--services postgres`, and defaults `connection-string` and `inspect db` to `neondb_owner` on Data API branches. The surface diff and errors below were run in throwaway Linux sandboxes on 2026-10-10.",
  "latest": {
    "version": "8.3.5",
    "released_at": "2026-10-09T16:44:06Z",
    "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.5"
  },
  "upgrade": [
    {
      "label": "npm (neonctl compatibility package)",
      "command": "npm i -g neonctl@latest\nneonctl --version   # 8.3.5"
    },
    {
      "label": "npm (neon package directly)",
      "command": "npm i -g neon@latest\nneon --version      # 8.3.5"
    },
    {
      "label": "pnpm",
      "command": "pnpm add -g neonctl@latest"
    },
    {
      "label": "Homebrew (community formula)",
      "command": "brew install neonctl"
    },
    {
      "label": "Pin a specific version",
      "command": "npm i -g neonctl@8.3.5"
    }
  ],
  "verified": {
    "date": "2026-10-10",
    "version": "8.3.5",
    "method": "Ran `bin/tool-snapshot neonctl 8.0.11`, `bin/tool-snapshot neonctl 8.3.5`, and `bin/tool-diff neonctl 8.0.11 8.3.5` in throwaway Linux sandboxes. Reproduced the credential-free `me`, non-TTY `init`, and `config init --services none` cases in one additional sandbox call."
  },
  "updated_at": "2026-10-10T11:41:00Z",
  "key_facts": [
    "Latest release: 8.3.5 on 2026-10-09 16:44 UTC. The npm package exposes both `neonctl` and `neon` binaries.",
    "The committed 8.0.11 to 8.3.5 help diff adds `neonctl login` and removes `neonctl auth` from the command list. In 8.3.5, `auth` remains an alias of `login`.",
    "`neon deploy` and `neon config apply` show `-y, --yes`; the flag answers the `--update-existing` and `--allow-protected` confirmations.",
    "`neon init --services postgres` is the Postgres-only starter policy. The older `--services none` spelling now fails.",
    "`neon connection-string` and `neon inspect db` default to `neondb_owner` on branches with Data API or Neon Auth roles. Use `--role-name` when more than one application role remains.",
    "`neon snapshots restore` and `update` skip the snapshot listing when given a snapshot ID. `create` and `schedule get` / `set` skip the branch listing when given a branch ID.",
    "`neon env pull` names the branch in its summary, and `neon init -y` completes the local setup path without credentials instead of stopping partway."
  ],
  "releases": [
    {
      "version": "8.3.5",
      "released_at": "2026-10-09T16:44:06Z",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.5",
      "changes": [
        {
          "text": "`neon connection-string` and `neon inspect db` default to `neondb_owner` on branches with the Data API or Neon Auth roles; pass `--role-name` when multiple application roles remain.",
          "url": "https://github.com/neondatabase/neon-pkgs/pull/795"
        },
        {
          "text": "The release also fixes two Neon Auth server endpoint paths and removes an unused JWKS entry.",
          "url": "https://github.com/neondatabase/neon-pkgs/pull/803"
        }
      ]
    },
    {
      "version": "8.3.4",
      "released_at": "2026-10-09T05:11:40Z",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.4",
      "changes": [
        {
          "text": "`neon inspect db` resolves the branch once, lists its databases once, and reads endpoints, roles, and databases concurrently.",
          "url": "https://github.com/neondatabase/neon-pkgs/pull/794"
        }
      ]
    },
    {
      "version": "8.3.3",
      "released_at": "2026-10-09T04:11:38Z",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.3",
      "changes": [
        {
          "text": "Human table labels spell abbreviations as `ID`, `URL`, `MiB`, and `PIDs`; JSON and YAML output are unchanged.",
          "url": "https://github.com/neondatabase/neon-pkgs/pull/786"
        }
      ]
    },
    {
      "version": "8.3.2",
      "released_at": "2026-10-09T03:21:04Z",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.2",
      "changes": [
        {
          "text": "`neon init -y` finishes the local setup path without authentication; with `--org-id`, `--project-id`, and `--branch`, it writes `.neon` offline and prints the next login step.",
          "url": "https://github.com/neondatabase/neon-pkgs/pull/792"
        }
      ]
    },
    {
      "version": "8.3.1",
      "released_at": "2026-10-09T01:19:22Z",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.1",
      "changes": [
        {
          "text": "`neon snapshots restore` and `update` skip the snapshot listing when given a snapshot ID; `create` and `schedule get` / `set` skip the branch listing when given a branch ID.",
          "url": "https://github.com/neondatabase/neon-pkgs/pull/789"
        }
      ]
    }
  ],
  "surface": [
    {
      "from": "8.0.11",
      "to": "8.3.5",
      "method": "`bin/tool-snapshot` ran `--help` for every neonctl subcommand of both versions in throwaway Linux sandboxes (199 and 199 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`.",
      "summary": "1 command added, 1 removed, 0 command-with-flag changes reported by the diff tool; 23 help pages changed in any way.",
      "commands_added": [
        "neonctl login"
      ],
      "commands_removed": [
        "neonctl auth"
      ],
      "flags": [
        {
          "command": "neonctl deploy",
          "added": [
            "-y",
            "--yes"
          ],
          "removed": []
        },
        {
          "command": "neonctl config apply",
          "added": [
            "-y",
            "--yes"
          ],
          "removed": []
        }
      ],
      "notes": [
        "The generated diff reports `neonctl login` added and `neonctl auth` removed. The 8.3.5 help still prints `auth` as the alias of `login`.",
        "The generated diff reports no command-with-flag changes because the new aliases share the existing apply option. The exact help text adds `-y, --yes` to `deploy` and `config apply`; PR #775 maps them to `--update-existing`, and PR #783 makes yes answer the protected-branch confirmation too.",
        "The same help diff documents `--services postgres` for `init` and `config init`, and the `--role-name` default for `connection-string` and every `inspect db` diagnostic."
      ]
    },
    {
      "from": "8.0.0",
      "to": "8.0.11",
      "method": "Built from source comparison of tags `neon@8.0.0` and `neon@8.0.11` via GitHub Compare API (from source, not run). Commands and flags verified against `packages/cli/src/commands/`.",
      "summary": "1 command added (`neon feedback`), 0 removed, 1 command with flags added (`feedback --message`); `roles create --no-login` parsing bug fixed.",
      "commands_added": [
        "neon feedback"
      ],
      "commands_removed": [],
      "flags": [
        {
          "command": "neon feedback",
          "added": [
            "--message"
          ],
          "removed": []
        }
      ],
      "notes": [
        "From source (not run). 8.0.2 introduced `neon feedback --message <text>` for anonymous feedback submission, and corrected `--no-login` flag parsing in `neon roles create`."
      ]
    },
    {
      "from": "7.0.8",
      "to": "8.0.0",
      "method": "Built from source comparison of tags `neon@7.0.8` and `neon@8.0.0` via GitHub Compare API (from source, not run). Architecture verified against `packages/cli/src/project.ts`.",
      "summary": "0 commands added, 0 removed, 0 commands with flags added or removed; project directory scoping enforced for `neon.ts` and `.env.local`.",
      "commands_added": [],
      "commands_removed": [],
      "flags": [],
      "notes": [
        "The 8.0.0 major transition. From source (not run): `neon.ts` and `.env.local` resolution moved into `packages/cli/src/project.ts`, locking config resolution to the directory containing `.neon`."
      ]
    }
  ],
  "breaking": [
    {
      "version": "8.3.5",
      "change": "On branches with Data API or Neon Auth roles, `connection-string` and `inspect db` prefer `neondb_owner` instead of failing because the branch exposes several roles. They still fail when more than one application role remains.",
      "migrate": "Use `--role-name <role>` when the branch has several application roles and the default is not the one you want.",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/795"
    },
    {
      "version": "8.2.0",
      "change": "`neon deploy` and `neon config apply` ask before applying to a protected branch or overriding settings already present on the branch.",
      "migrate": "For automation, pass `-y` or `--yes` in 8.3.5, or pass the narrower `--allow-protected` and `--update-existing` flags explicitly.",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/783"
    },
    {
      "version": "8.1.0",
      "change": "`neon init --services none` and `neon config init --services none` were removed. The service list now accepts `postgres` as the Postgres-only starter policy.",
      "migrate": "Replace `--services none` with `--services postgres`.",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/776"
    },
    {
      "version": "8.0.0",
      "change": "`neon.ts` and default `.env.local` are scoped to the project directory holding `.neon` (nearest at or above cwd, or `--context-file`), or cwd when unlinked. Parent directory `neon.ts` files are no longer automatically found from subdirectories.",
      "migrate": "Run `neon link` at repository root to create `.neon`, move `neon.ts` next to `.neon`, or pass `--config <path>` to target a custom configuration file.",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.0.0"
    },
    {
      "version": "7.0.0",
      "change": "Snapshot slugs were removed from the Neon Management API. `neon snapshots create --slug` is removed; snapshots resolve by ID or unique name.",
      "migrate": "Remove `--slug` from scripts; use `--name <name>` or a snapshot ID.",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%407.0.0"
    },
    {
      "version": "6.0.0",
      "change": "`neon init -y` standardized as Recommended setup with detected agents, link when authenticated, and a default `neon.ts`. Template flags were removed; the current directory is configured in place.",
      "migrate": "For custom setup in scripts, pass `--skill`, MCP flags, `--no-agent-setup`, or `--claimable`.",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%406.0.0"
    },
    {
      "version": "5.0.0",
      "change": "`neon link` requires a complete `.neon` context: organization when the project has one, project, and branch. Org-only, unpinned, and `--no-checks` writes without `--branch` fail.",
      "migrate": "Specify `--branch <branch>` when linking non-interactively without an active default branch.",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%405.0.0"
    },
    {
      "version": "4.0.0",
      "change": "`neon neon-auth config email-provider test` is restricted to custom SMTP configured on the branch. Connection flags (`--host`, `--port`, `--username`, `--password`) are rejected.",
      "migrate": "Save the email provider first with `neon neon-auth config email-provider update --type standard`, then pass only `--recipient-email` to test.",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%404.0.0"
    },
    {
      "version": "3.0.0",
      "change": "Functions `externalPackages` archives stage real files for native binaries on the linux-arm64 runtime target rather than packaging symlinks.",
      "migrate": "Declare native dependencies under `externalPackages` in `neon.ts` functions configuration.",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%403.0.0"
    }
  ],
  "gotchas": [
    {
      "title": "`neon me` reports signed out instead of starting browser auth",
      "version": "8.3.5",
      "command": "neonctl me",
      "output": "Not signed in: profile \"DEFAULT\" has no stored credential. Run `neonctl login --profile DEFAULT` to sign in, or use an API key with --api-key or NEON_API_KEY.",
      "fix": "Use `neonctl login` or `neon login` interactively, or set a valid `NEON_API_KEY`. `neon me` exits 1 as a signed-out check and does not open a browser.",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/774"
    },
    {
      "title": "Non-TTY `neon init` requires `-y`",
      "version": "8.3.5",
      "command": "neonctl init",
      "output": "ERROR: No interactive terminal. Re-run with -y to set up this directory with Recommended defaults: `neon init -y`. To pick each step instead, run `neon init` in a terminal, or see `neon init --help` for the flag that sets each step.",
      "fix": "Run `neon init -y` in CI or another non-interactive process. Run `neon init` in a terminal when you need to choose each setup step.",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/785"
    },
    {
      "title": "`--services none` is rejected in 8.1.0 and later",
      "version": "8.3.5",
      "command": "neonctl config init --services none --no-install",
      "output": "ERROR: Unknown service none. Supported values: postgres, auth, data-api, functions, object-storage, ai-gateway.",
      "fix": "Use `neonctl config init --services postgres --no-install` for the Postgres-only starter policy. The same replacement applies to `neon init --services`.",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/776"
    }
  ],
  "monthly": [
    {
      "month": "2026-10",
      "versions": "neon@7.0.2 to neon@8.3.5 (28 releases through 2026-10-09)",
      "highlights": [
        {
          "text": "8.0.12 to 8.1.0: checkout request reduction, `neon login` as the canonical sign-in command, `-y` / `--yes` deploy aliases, and `--services postgres`.",
          "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.1.0"
        },
        {
          "text": "8.2.0 to 8.3.0: deploy confirmation prompts, plain informational lines, branch-named env-pull summaries, and non-TTY `neon init` guidance.",
          "url": "https://github.com/neondatabase/neon-pkgs/pull/783"
        },
        {
          "text": "8.3.1 to 8.3.5: fewer snapshot-list requests, unauthenticated `init -y` completion, acronym labels, concurrent inspect reads, and `neondb_owner` role selection.",
          "url": "https://github.com/neondatabase/neon-pkgs/pull/795"
        }
      ]
    },
    {
      "month": "2026-09",
      "versions": "neon@4.13.1 to neon@7.0.1 (34 releases)",
      "highlights": [
        {
          "text": "Three majors: 5.0.0 (link requires complete `.neon`), 6.0.0 (standardized `neon init -y`), and 7.0.0 (snapshot slugs removed).",
          "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%407.0.0"
        },
        {
          "text": "7.0.0: in-process step runner for init and bootstrap, replacing child-process execution.",
          "url": "https://github.com/neondatabase/neon-pkgs/blob/neon%408.3.5/packages/cli/CHANGELOG.md"
        }
      ]
    },
    {
      "month": "2026-08",
      "versions": "neon@2.39.0 to neon@4.13.0 (40 releases)",
      "highlights": [
        {
          "text": "Two majors: 3.0.0 (Functions `externalPackages` binary staging and the monorepo transition) and 4.0.0 (email-provider test restricted).",
          "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%403.0.0"
        },
        {
          "text": "Added `neon inspect db stalled-queries` for read-only inspection of queries running over 30s.",
          "url": "https://github.com/neondatabase/neon-pkgs/blob/neon%408.3.5/packages/cli/CHANGELOG.md"
        }
      ]
    },
    {
      "month": "2026-07",
      "versions": "neonctl@2.29.2 to neon@2.38.5 (25 releases)",
      "highlights": [
        {
          "text": "Monorepo transition: dual publishing of `neon` and `neonctl` packages; agent tooling (`neon skills`, `neon mcp`) introduced.",
          "url": "https://github.com/neondatabase/neon-pkgs"
        }
      ]
    },
    {
      "month": "2026-06",
      "versions": "2.22.2 to neonctl@2.29.1 (21 releases)",
      "highlights": [
        {
          "text": "Final v2.27.0 release on the standalone `neondatabase/neonctl` repository on 2026-06-22 before archiving.",
          "url": "https://github.com/neondatabase/neonctl/releases/tag/v2.27.0"
        },
        {
          "text": "The monorepo `neondatabase/neon-pkgs` was seeded with `neonctl@2.27.1` through `neonctl@2.29.1`.",
          "url": "https://github.com/neondatabase/neon-pkgs"
        }
      ]
    },
    {
      "month": "2026-05",
      "versions": "none (0 releases)",
      "highlights": [
        {
          "text": "Development hiatus between standalone v2.22.0 in March 2026 and the monorepo transition in June 2026.",
          "url": "https://github.com/neondatabase/neonctl"
        }
      ]
    }
  ],
  "sources": [
    {
      "title": "neondatabase/neon-pkgs releases (GitHub API)",
      "url": "https://api.github.com/repos/neondatabase/neon-pkgs/releases",
      "read": "2026-10-10"
    },
    {
      "title": "neonctl on the npm registry",
      "url": "https://registry.npmjs.org/neonctl",
      "read": "2026-10-10"
    },
    {
      "title": "neon on the npm registry",
      "url": "https://registry.npmjs.org/neon",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 8.0.12 release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.0.12",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 8.1.0 release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.1.0",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 8.2.0 release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.2.0",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 8.3.0 release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.0",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 8.3.1 release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.1",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 8.3.2 release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.2",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 8.3.3 release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.3",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 8.3.4 release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.4",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 8.3.5 release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.3.5",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 8.0.11 to 8.3.5 compare",
      "url": "https://github.com/neondatabase/neon-pkgs/compare/neon%408.0.11...neon%408.3.5",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #761: reduce checkout round trips",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/761",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #775: deploy yes aliases",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/775",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #776: Postgres-only service selection",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/776",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #778: login command",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/778",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #774: signed-out me behavior",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/774",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #782: informational lines",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/782",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #783: deploy confirmations",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/783",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #785: non-TTY init guidance",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/785",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #788: env pull branch heading",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/788",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #789: snapshot request reduction",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/789",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #792: unauthenticated init completion",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/792",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #786: table acronym labels",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/786",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #794: inspect db concurrent reads",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/794",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI PR #795: default connection role",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/795",
      "read": "2026-10-10"
    },
    {
      "title": "Neon Auth PR #803: endpoint paths",
      "url": "https://github.com/neondatabase/neon-pkgs/pull/803",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 8.0.0 major release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%408.0.0",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 7.0.0 major release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%407.0.0",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 6.0.0 major release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%406.0.0",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 5.0.0 major release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%405.0.0",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 4.0.0 major release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%404.0.0",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI 3.0.0 major release notes",
      "url": "https://github.com/neondatabase/neon-pkgs/releases/tag/neon%403.0.0",
      "read": "2026-10-10"
    },
    {
      "title": "Neon CLI official documentation",
      "url": "https://neon.com/docs/reference/cli",
      "read": "2026-10-10"
    }
  ],
  "fixes": []
}