This article follows the official documentation. We haven’t tested this tool for a hands-on review.
When a coding agent needs a separate Neon database to test a change to a database’s structure, called a schema change, the Neon CLI can create a branch and retrieve its connection string. A database branch is a separate copy of a Neon database. It lets an agent test changes without writing to the branch it was copied from.
The CLI sends commands to Neon’s hosted service, so creating a branch changes your Neon project. The connection string contains database credentials; keep it out of agent prompts and logs. The commands below follow Neon’s documentation and have not been run for this article.
What the CLI does
Neon’s command-line interface lets you manage Neon projects, database branches, and connection strings from a terminal. An agent that can run terminal commands can use the CLI to set up a separate database for tests or development. Neon explains its branching workflow in its local development guide.
The CLI manages databases hosted by Neon. When the CLI creates a branch, it does not install PostgreSQL on the developer’s machine. The agent can use the branch’s connection string with the project’s existing database client or test configuration.
Set up access
For an agent-oriented setup, Neon documents this command:
npx neon@latest init
The setup uses OAuth, a sign-in flow, to authenticate, creates a Neon API key, a credential for accessing Neon, and configures the selected editor or CLI integration. It also installs Neon’s agent skills, which give coding assistants context about Neon features and recommended usage. See Neon’s AI agent setup.
For CLI authentication, Neon documents neon login. Run neon login in a terminal where the Neon CLI is available, then complete sign-in. Keep API keys and database credentials in the environment or secret store used by your development setup; do not put them in the prompt you give the agent. Neon’s CLI page has the current installation and command details.
Create a branch for a test
Suppose an agent needs a database branch to test a migration, a change to the database’s structure. After you authenticate, create a branch with a name:
neon branches create --name dev/your-name
Replace your-name with a branch name that identifies the work. This command creates a branch in Neon, so it is a service-side change rather than a local preview. Neon documents the command as part of its branching workflow.
Then retrieve the branch’s connection string:
neon connection-string dev/your-name
This command returns the details your test client uses to connect to the branch. Treat the output as a secret. Store it in an appropriate environment variable or secret manager rather than including it in the agent’s instructions or committing it to the repository. The agent can then run the project’s existing tests against the branch, provided its test configuration accepts that connection string.
“Create a Neon branch named dev/migration-check, save its connection string in the existing local test environment, and run the migration tests against that branch. Do not use the production connection string or print credentials in your response.” The prompt should name the intended branch and the project’s existing way to configure test credentials; the agent should not guess either.
Know what changes remotely
Branch creation adds a branch to the Neon project. Retrieving a connection string reads connection details, but sharing or logging those details exposes credentials. Neon’s branching model isolates development work from the parent branch, while the branch remains a resource in the hosted Neon project.
The example uses only documented commands and does not include an output-format flag or preview option. If an agent should not create remote resources without approval, ask it to stop before neon branches create and request confirmation. For an already existing branch, the connection-string command avoids creating a new one.
Neon also offers setup for editor integrations, skills, and other tools. This setup is separate from the CLI’s branch commands. Choose it when the agent needs Neon-specific coding context as well as terminal access.