Giving AI Agents a Safe Interface to Nearbase

An AI agent can write an application, configure a deployment, and investigate an incident. It should also be able to answer a simple infrastructure question: what databases do I have, and what would it take to create another one?

Today we’re making the Nearbase CLI usable as that interface.

The important word is interface. We did not give agents direct access to our cloud provider, database passwords, or payment details. We extended the same small CLI people already use, backed it with explicit contracts, and put hard boundaries around anything that can spend money.

A CLI that machines can depend on

The original Nearbase CLI was designed for humans. It displayed a table, used colors and spinners, and opened a browser during login. That is pleasant in a terminal, but unreliable for software trying to call it.

The CLI now has a global --json mode with stable success and error envelopes:

{
  "ok": true,
  "data": {
    "instances": []
  }
}

Errors have stable codes such as AUTH_REQUIRED, VALIDATION_ERROR, PRICE_CHANGED, and RATE_LIMITED. They go to stderr, while successful data goes to stdout. Exit codes distinguish usage, authentication, and API failures.

That gives an agent a real contract instead of asking it to scrape a table or guess what a sentence means.

What agents can do

An authenticated agent can now:

• list instances across organizations, or scope the request to one organization;
• inspect instance metadata without receiving a connection string;
• discover regions, PostgreSQL versions, and offered instance classes;
• calculate the current monthly price for a configuration;
• ask Nearbase and the underlying provider to validate a configuration with a dry run;
• request a short-lived create quote;
• submit a previously approved quote for creation.

For example:

nearbase --json ls --org acme

nearbase --json price \
  --region ap-southeast-1 \
  --engine-version 16 \
  --db-instance-class <class-code> \
  --db-instance-storage 20 \
  --db-instance-storage-type general_essd \
  --category Basic

Every write is explicitly scoped with --org. Read access still follows the user’s current organization memberships, so removing a user from an organization also removes the CLI’s access on the next request.

Creating without giving an agent a credit card

Database creation is where a convenient automation can become an expensive mistake. A retry, duplicate tool call, or misunderstood prompt should not create two databases or silently charge a card.

Nearbase uses a two-step flow.

First, the agent submits the desired configuration. Nearbase validates the SKU, calculates the authoritative price, checks available credits, and returns a quote that expires after ten minutes. Nothing is charged and nothing is provisioned.

nearbase --json create \
  --org acme \
  --region ap-southeast-1 \
  --engine-version 16 \
  --db-instance-class <class-code> \
  --db-instance-storage 20 \
  --db-instance-storage-type general_essd \
  --category Basic \
  --display-name agent-staging

Second, the exact quote must be confirmed with a stable idempotency key:

nearbase --json create \
  --confirm <quote-id> \
  --idempotency-key deploy-2026-09-08-staging-db

At confirmation time, Nearbase checks the user’s organization membership, availability, price, and credit balance again. If any of them changed, the request is rejected and the agent must obtain a new quote.

If credits cover the total, the existing asynchronous provisioning pipeline starts. If a card is required, the CLI returns a Stripe Checkout URL for a person to open and complete. The agent never handles card details.

Retries are safe across the whole path. The quote binds to one idempotency key, Stripe receives its own idempotency key, billing subscriptions carry a stable operation ID, and ledger entries are protected by a database uniqueness constraint.

Authentication for local and remote agents

The browser-based device flow remains the default:

nearbase login

For a remote terminal, nearbase --json login --no-open prints the verification URL and code without trying to launch a browser. A person still approves the request with their Nearbase account.

Once authorized, an agent can use the protected local token file or receive a token through the NEARBASE_TOKEN environment variable. This makes the CLI work in managed agent and CI environments without weakening the initial human authorization step.

What agents still cannot do

We are deliberately not exposing:

• database connection strings or passwords;
• deletion or subscription cancellation;
• security IP changes;
• payment-method management;
• start, stop, or restart operations.

Those operations either expose credentials, change network access, destroy data, or are not yet implemented in the Nearbase lifecycle layer. A machine interface should not be wider than the product’s safety model.

Provider-backed dry runs are also limited per user and organization. Automation does not need an unlimited path to a cloud API.

Why start with the CLI instead of a new agent protocol?

The CLI was already a thin client over Nearbase’s authenticated API. Extending it gave us one interface that works from a terminal, a shell script, CI, or an AI agent.

It also keeps the boundary easy to inspect. An agent invokes a command, receives JSON, and acts on a documented result. There is no separate infrastructure control plane and no cloud credential installed on the agent’s machine.

Native agent tools may come later. If they do, they can wrap the same REST contracts and safety checks rather than inventing another way to create a database.

Try it

npm install -g @nearbase/cli
nearbase login
nearbase --json regions
nearbase --json ls

The full command reference and create workflow are in the Nearbase CLI documentation.