> This page location: Tools & Workflows > API, CLI & SDKs > CLI > psql
> Full Neon documentation index: https://neon.com/docs/llms.txt

> Summary: Covers the usage of the `psql` command in the Neon CLI to open a psql session against a branch in your Neon project, including pooled connections and time-travel support.

# Neon CLI command: psql

Connect to a Neon database via psql

## Before you begin

- Before running the `psql` command, ensure that you have [installed the Neon CLI](https://neon.com/docs/reference/cli-install).
- The `psql` command requires **neonctl 2.22.2** or later. Check your version with `neon --version`.
- The [`psql`](https://www.postgresql.org/docs/current/app-psql.html) client must be installed on your system.
- If you have not authenticated with the [neon auth](https://neon.com/docs/reference/cli-auth) command, running a Neon CLI command automatically launches the Neon CLI browser authentication process. Alternatively, you can specify a Neon API key using the `--api-key` option when running a command. See [Connect](https://neon.com/docs/reference/neon-cli#connect).

## The `psql` command

The `psql` command connects to a database in your Neon project using the `psql` client. It builds a connection string for the specified branch (or the default branch from your [context file](https://neon.com/docs/reference/cli-set-context)) and launches `psql`.

This is equivalent to running [`neon connection-string --psql`](https://neon.com/docs/reference/cli-connection-string), but as a dedicated top-level command.

### Usage

```bash
neon psql [branch] [options] [-- psql-args]
```

`branch` specifies the branch name or ID. If omitted, the default branch from your context (or the project's default branch) is used. You can also use the point-in-time format `branch@timestamp` or `branch@lsn` for [time travel](https://neon.com/docs/guides/time-travel-assist) connections.

Arguments after `--` are forwarded to `psql`.

### Options

In addition to the Neon CLI [global options](https://neon.com/docs/reference/neon-cli#global-options), the `psql` command supports these options:

| Option            | Description                                                                                 | Type    |                       Required                      |
| ----------------- | ------------------------------------------------------------------------------------------- | ------- | :-------------------------------------------------: |
| `--context-file`  | [Context file](https://neon.com/docs/reference/cli-set-context) path and file name          | string  |                                                     |
| `--project-id`    | Project ID                                                                                  | string  | Only if your Neon account has more than one project |
| `--role-name`     | Role name                                                                                   | string  |      Only if your branch has more than one role     |
| `--database-name` | Database name                                                                               | string  |    Only if your branch has more than one database   |
| `--pooled`        | Use a pooled connection. The default is `false`.                                            | boolean |                                                     |
| `--endpoint-type` | The compute type. The default is `read_write`. The choices are `read_only` and `read_write` | string  |                                                     |
| `--ssl`           | SSL mode. The default is `require`.                                                         | string  |                                                     |

### Examples

Connect to the default branch:

```bash
neon psql
```

Connect to a named branch. New Neon projects create a default branch named `production`:

```bash
neon psql production
```

Run a single query:

```bash
neon psql production -- -c "SELECT version()"
```

Run an SQL file:

```bash
neon psql production -- -f dump.sql
```

Connect to a branch at a specific point in time:

```bash
neon psql production@2024-01-01T00:00:00Z
```

Use a pooled connection:

```bash
neon psql --pooled
```

---

## Related docs (CLI)

- [Overview](https://neon.com/docs/reference/neon-cli)
- [Quickstart](https://neon.com/docs/reference/cli-quickstart)
- [Install and connect](https://neon.com/docs/reference/cli-install)
- [auth](https://neon.com/docs/reference/cli-auth)
- [me](https://neon.com/docs/reference/cli-me)
- [orgs](https://neon.com/docs/reference/cli-orgs)
- [projects](https://neon.com/docs/reference/cli-projects)
- [ip-allow](https://neon.com/docs/reference/cli-ip-allow)
- [vpc](https://neon.com/docs/reference/cli-vpc)
- [branches](https://neon.com/docs/reference/cli-branches)
- [checkout](https://neon.com/docs/reference/cli-checkout)
- [databases](https://neon.com/docs/reference/cli-databases)
- [roles](https://neon.com/docs/reference/cli-roles)
- [operations](https://neon.com/docs/reference/cli-operations)
- [connection-string](https://neon.com/docs/reference/cli-connection-string)
- [link](https://neon.com/docs/reference/cli-link)
- [set-context](https://neon.com/docs/reference/cli-set-context)
- [data-api](https://neon.com/docs/reference/cli-data-api)
- [init](https://neon.com/docs/reference/cli-init)
- [completion](https://neon.com/docs/reference/cli-completion)