# Quickstart

> Install the CLI, create a Postgres database, and branch it to test changes

> Nevia is in beta and open to selected teams. Public launch in Dec 2026. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/get-started/quickstart

You will install the `nevia` CLI, create a Postgres database and branch it. The
branch is a full copy of your data that you can change while the original keeps
running. It takes about ten minutes. To do the same exercise through your agent,
use [Quickstart with MCP](https://nevia.cloud/docs/get-started/mcp.md).

## Prerequisites

You need:

* A local terminal with `curl`, and a browser for sign-in.
* The `psql` Postgres client, to run the SQL examples.
* A Nevia workspace where you have the **admin** or **editor** role. If you
  don’t belong to one yet, Nevia creates a `default` workspace on your first
  sign-in.

To install `psql`, use the command for your system:

```bash
# macOS
brew install libpq && brew link --force libpq

# Debian / Ubuntu
sudo apt install postgresql-client
```

Check that it works:

```bash
psql --version
```

This prints the client version.

## 1. Install the CLI and sign in

Install the CLI:

```bash
curl -fsSL https://get.nevia.cloud | sh
```

If the install directory isn't on your `PATH`, the installer prints the
`export` command to run and the shell file to add it to. Then check that the
CLI runs:

```bash
nevia --version
```

This prints the CLI version.

The installer supports macOS 11 or later and Linux kernel 4.18 or later, on
ARM64 and x86-64. It needs `curl`, `tar` with gzip support, `mktemp`, and
either `sha256sum` or `shasum`. It verifies the download before replacing an
existing installation, so run the same command again to upgrade. You can also
run `nevia update` to upgrade in place, or `nevia update --dry-run` to only
compare versions. [`nevia update`](https://nevia.cloud/docs/reference/cli/update.md) explains when the
CLI asks to update itself.

To pin a version or choose another install directory, pass variables to `sh`:

```bash
curl -fsSL https://get.nevia.cloud | NEVIA_VERSION=0.1.7 sh
curl -fsSL https://get.nevia.cloud | NEVIA_INSTALL_DIR="$HOME/bin" sh
```

Then sign in. `nevia login` opens your browser and stores the credential in your config
directory. The browser ends on the console, already signed in. `nevia whoami` shows who
you are and lists your workspaces with your role in each:

```bash
nevia login
nevia whoami
```

If you belonged to no workspace, Nevia created one named `default`. While it is your
only workspace, commands use it and you can skip to the next step. Otherwise, pick a
workspace from `whoami` where you have the admin or editor role. Copy its full ID and
replace `01d4cnjjq40hnnh0nwmkg35nv2h` below with it:

```bash
nevia workspace use 01d4cnjjq40hnnh0nwmkg35nv2h
nevia workspace current
```

Use the ID even if the workspace is named `default`, because creation and workspace
management commands require it. `nevia workspace current` should print the ID you
selected. If it prints something else, see [Select a workspace](https://nevia.cloud/docs/workspaces/select.md)
for overrides. To create another workspace, see
[Create a workspace and manage access](https://nevia.cloud/docs/workspaces/manage.md).

## 2. Create a database

Version, size and storage take platform defaults, so the command needs only a name.
Use a workspace where `orders` and `orders-staging` are free.

```bash
nevia pg create orders
```

Check that the database is ready:

```bash
nevia pg ls
```

`orders` should be ready, with no pending transition. If creation is still running,
run the command again or [track the operation](https://nevia.cloud/docs/guides/operations.md) before
connecting.

Get the connection details and password:

```bash
nevia pg connect orders
```

[`nevia pg connect orders`](https://nevia.cloud/docs/reference/cli/pg/connect.md) prints the connection details
and reads the password back from the machine when you need it. Add `--uri` to print
only the `postgres://` URI for `psql` and scripts. The URI reaches the database
directly, with no tunnel in between.

Keep the URI's `sslmode=require` or stricter setting, because routing requires TLS.
A `ready` state does not prove your client can connect. The first query below does.
If the endpoint is unreachable or reports that SSL is unavailable, see
[Create and connect to a database](https://nevia.cloud/docs/databases/create.md).

## 3. Set up a schema and some data

Pipe a schema and some rows into the database. This heredoc creates a table, inserts
four rows and counts them:

```bash
psql "$(nevia pg connect orders --uri)" <<'SQL'
CREATE TABLE IF NOT EXISTS pings (id serial PRIMARY KEY, note text);
INSERT INTO pings (note) VALUES
  ('csv-note-one'), ('csv-note-two'), ('baseline-a'), ('baseline-b');
SELECT count(*) FROM pings;
SQL
```

The count is 4.

## 4. Branch the database

Branching copies the parent's current data into a new database with its own connection
string. The source must be ready, with no pending transition or running operation,
and must have a persistent data disk supplied by the deployment.

```bash
nevia pg branch orders -b orders-staging
nevia pg status orders-staging
```

Wait until `orders-staging` is ready, with no pending transition, before running the
SQL below. If it is still starting, check its status again.

The parent keeps running, and the branch records the ID of `orders` as its parent.
The branch uses the same credentials, which `pg connect` reads from its machine, and
starts with the same four rows. These statements change the branch only:

```bash
psql "$(nevia pg connect orders-staging --uri)" <<'SQL'
INSERT INTO pings (note) VALUES ('branch-mutation');
UPDATE pings SET note = 'baseline-a (edited in branch)' WHERE note = 'baseline-a';
SQL
```

`psql` prints `INSERT 0 1` and `UPDATE 1`.

## 5. Check the divergence

Run the same query against both databases:

```bash
for db in orders orders-staging; do
  psql "$(nevia pg connect "$db" --uri)" -c \
    "SELECT count(*), array_agg(note ORDER BY id) FROM pings;"
done
```

The parent still has 4 rows. The branch has 5: the new `branch-mutation` row, and
`baseline-a` rewritten to `baseline-a (edited in branch)`. Your edits changed a full
copy, and the original is untouched.

## Next steps

Open the [console](https://console.nevia.cloud/) to see `orders` and `orders-staging`
side by side under Databases. Then:

* [Create your first computer](https://nevia.cloud/docs/get-started/first-computer.md) continues here: run a web app on a computer and open it on an HTTPS URL.
* [Create and connect to a database](https://nevia.cloud/docs/databases/create.md) covers creation and TLS connections.
* [Branch a database](https://nevia.cloud/docs/databases/branch.md) shows how to copy an existing database.
* [Sleep, wake and delete a database](https://nevia.cloud/docs/databases/lifecycle.md) covers lifecycle actions and protection.

To clean up, delete the branch and its data first:

```bash
nevia pg rm orders-staging --yes
nevia pg ls
```

Once `orders-staging` no longer appears in the list, delete the source and its data:

```bash
nevia pg rm orders --yes
nevia pg ls
```

Neither database should appear in the list. If deletion is still running, run
`nevia pg ls` again.