> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Authenticate, list resources, and connect with the Formal CLI

See [Configuration](/docs/guides/client-apps/configuration) for `~/.formal/config.toml`.

### Authentication

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
# Log in
formal auth login

# Get your credentials (for direct connections)
formal auth credentials
```

### List Resources

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
formal ls
```

Interactive TUI with:

* `↑/k` - Move up
* `↓/j` - Move down
* `enter` - Connect to resource
* `/` - Filter resources
* `q` - Quit
* `?` - Show help

### Connect to Resources

#### Databases (PostgreSQL, MySQL, MongoDB)

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
# Connect to a database
formal connect production-postgres

# Output:
# Connected to production-postgres on localhost:6432
```

Then connect with your database client:

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
# PostgreSQL
psql -h localhost -p 6432 -d postgres

# MySQL
mysql -h localhost -P 4306 -D mysql

# MongoDB
mongosh "mongodb://localhost:37017/mydb"
```

**Formal automatically injects your credentials** - no username/password needed!

Note that the database name is required for the connection to be successful.

You can also use the `--launch` argument to launch the appropriate CLI program after connecting (for example `psql` or `ssh`), e.g.

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
# uses the database name from the config file in ~/.formal/config.toml
formal connect --launch production-postgres
```

#### Specify Native User

To request a Native User instead of the Resource's assigned default, append its label using `formal@<native_user_label>`.

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
# PostgreSQL with the "readonly" Native User label
psql -h localhost -p 6432 -U formal@readonly
```

See [Native Users](/docs/guides/core-concepts/resources/native-users) for label selection and policy controls.

#### Specify Resource Hostname

If a resource has multiple [Resource Hostnames](/docs/guides/core-concepts/resources/tls#resource-hostnames) (for example, separate reader and writer endpoints), target one by appending `@<hostname-name>` to the resource name:

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
# Connect to the "postgres-reader" hostname on the production-postgres resource
formal connect production-postgres@postgres-reader
```

<Note>
  Resource hostname targeting is currently supported for PostgreSQL and MySQL resources.
</Note>

Connect with your database client as usual, using the port from the `formal connect` output:

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
# PostgreSQL
psql -h localhost -p 6432 -d postgres

# MySQL
mysql -h localhost -P 4306 -D mysql
```

Use the same `RESOURCE_NAME@HOSTNAME_NAME` target to disconnect:

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
formal disconnect production-postgres@postgres-reader
```

#### SSH

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
# List resources
formal ls
# Select an SSH resource and press enter
```

This updates your `~/.ssh/config` automatically.

#### Configure SSH without write access

Formal adds the following block to the top of `~/.ssh/config` on your first SSH connection:

```ssh-config theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
# START FORMAL-MANAGED BLOCK
# Do not hand-edit this section.
Include ~/.formal/ssh_config
# END FORMAL-MANAGED BLOCK
```

If Formal cannot modify this file, add the block manually before any `Host` entries. Then run `formal connect <resource-name>` again.

Formal writes subsequent SSH resource changes to `~/.formal/ssh_config`.

#### Kubernetes

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
# Configure kubectl
formal ls
# Select a Kubernetes resource and press enter
```

This updates your `~/.kube/config` to route through the Connector.

### Disconnect

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
# Disconnect from a resource
formal disconnect production-postgres
```

### Decrypt Data

Decrypt Formal-encrypted data:

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
formal decrypt --ciphertext "formalencrypt:second:third:fourth:fifth"
```

### S3 Operations

The Formal `s3` command automatically routes traffic to the right Connector so your users don't have to worry about formatting the right parameters for S3.

Interact with S3 through Formal:

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
formal s3 ls s3://my-bucket
```

See [AWS CLI S3 commands](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html) for more operations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.