# CLI

> The dna command line for agent identities: install, sign in through the browser, create identities, wait for mail, pull out the code and clean up, from a terminal or CI.

Source: https://docs.dissolve.email/cli

`dna` makes [agent identities](/agent) from a terminal or a script: an email address and a password for one sign-up, the mail it receives and the verification code inside. The binary is `dna`, the name it had as the destroy.network CLI so scripts keep working, and it is also installed as `dissolve`. Both are the same program.

Agent identities and API keys need a Pro or Business plan.

## Install

```bash npm
npm install -g @dissolve-email/cli
```

```bash Go
go install github.com/dissolve-email/dissolve-cli@latest            # installs dna
go install github.com/dissolve-email/dissolve-cli/cmd/dissolve@latest   # installs dissolve
```

The npm package brings a pre-built binary for Linux, macOS and Windows on x64, and arm64 on Linux and macOS; no Go toolchain needed.

## Quick start

```bash
dna auth login                         # approve in the browser
ID=$(dna create --label signup --json | jq -r .id)
EMAIL=$(dna get "$ID" --json | jq -r .email)
# ... sign up somewhere with $EMAIL ...
dna verify "$ID" --timeout 30 --quiet  # prints the code
dna delete "$ID"
```

## Sign in

`dna auth login` signs in with a device flow:

1. The CLI asks [POST /api/cli/device](/reference/cli#start-the-cli-device-flow) for a one-time code and shows it.
2. It opens `https://app.dissolve.email/cli/auth?code=XXXX-XXXX`. Sign in if asked. The page shows when the request was made, from where, from which address and device. Check the code matches your terminal and press Approve, or Deny. Opening the page alone approves nothing.
3. The CLI polls [POST /api/cli/token](/reference/cli#poll-for-the-cli-s-key) and saves the new `sk_live_` key to `~/.config/dissolve/config.json` with `0600` permissions.

If a key is already saved, `login` asks before replacing it. The new key appears among your [API keys](/api-keys) and counts against the plan's number of keys.

The key is taken from, in order:

1. the `--api-key` flag,
2. the `DISSOLVE_API_KEY` environment variable (`DESTROY_API_KEY` still works),
3. the config file.

| Command | Does |
|---|---|
| `dna auth login` | Signs in through the browser and saves a key |
| `dna auth status` | Shows whether a key is set, where it came from (masked) and the API address |
| `dna auth logout` | Removes the saved key from the config file |
| `dna account` | Your plan, key and identity counts and rate limit |

## Commands

| Command | Does |
|---|---|
| `dna create` | Makes an identity: an inbox and a generated password |
| `dna list` (`ls`) | Lists live identities |
| `dna get <id>` | One identity with its message count |
| `dna extend <id>` | Moves its expiry and changes its label |
| `dna delete <id>` (`rm`) | Deletes the identity, its inbox and every message |
| `dna messages <id>` | Lists the identity's messages |
| `dna message <id> <message-id>` | Reads one message |
| `dna wait <id>` | Waits for the next message |
| `dna verify <id>` | Finds a verification code or magic link |
| `dna config` | Reads and writes the config file |
| `dna tui` | A full-screen dashboard |
| `dna completion <shell>` | Shell completions for bash, zsh and fish |

### create

```bash
dna create
dna create --ttl 60 --label "twitter-signup"
dna create --prefix bot --password-length 24
dna create --persona --country US --gender female --label "signup"
```

| Flag | Default | Does |
|---|---|---|
| `--ttl` | the plan's default | Minutes until it expires |
| `--prefix` | random | Start of the address (letters and digits) |
| `--domain` | the default domain | A receiving domain |
| `--label` | none | What it is for |
| `--password-length` | 16 | Length of the generated password |
| `--persona` | off | Also make a fictional person: name, address, phone, birthday |
| `--no-persona` | off | Skip the persona even when the config turns it on |
| `--country` | random | The persona's country: US, UK, AU, CA, DE, FR, JP, BR, IN, ES, IT, NL, KR, MX, SE, PL or NZ |
| `--gender` | random | The persona's gender: `male` or `female` |

The password is printed when the identity is made: keep it, or save it in the [vault](/vault). With `--quiet` only the address is printed.

### extend

```bash
dna extend "$ID" --ttl 120          # expires 120 minutes from now
dna extend "$ID" --label "renamed"
```

| Flag | Does |
|---|---|
| `--ttl` | Minutes from now until it expires, within the plan's longest inbox life |
| `--label` | A new label |

### delete

```bash
dna delete "$ID"
dna delete "$ID" --keep-inbox       # delete only the identity, keep the inbox and its mail
```

### messages, message and wait

```bash
dna messages "$ID"
dna message "$ID" "$MESSAGE_ID"
dna message "$ID" "$MESSAGE_ID" --html
dna wait "$ID" --timeout 60
```

| Flag | Command | Default | Does |
|---|---|---|---|
| `--html` | message | off | Shows the HTML body instead of the text |
| `--timeout`, `-t` | wait | 30 | Seconds to wait, capped by the plan (Pro 30, Business 120) |

### verify

```bash
dna verify "$ID"                                    # check once
dna verify "$ID" --timeout 30                       # wait up to 30 s for one
dna verify "$ID" --from github.com                  # only mail from this sender
dna verify "$ID" --pattern "code:\s*(\d{6})"        # narrow the matches locally
```

| Flag | Default | Does |
|---|---|---|
| `--timeout`, `-t` | 0 | Seconds to wait for a code, capped by the plan |
| `--from` | none | Only mail whose sender contains this text, checked by the server |
| `--pattern`, `-p` | none | A regular expression run locally on the matches the server found; its first capture group is the value |

With `--quiet` it prints the value alone, ready for `$(...)`. [Codes and waiting](/verification) explains what counts as a code.

### config

```bash
dna config list
dna config get defaults.country
dna config set defaults.persona true
dna config unset defaults.country
```

| Key | Default | Does |
|---|---|---|
| `api_key` | none | The saved API key |
| `api_url` | `https://api.dissolve.email/api` | The API address |
| `defaults.persona` | `false` | Make a persona on every `create` |
| `defaults.country` | none | The persona country when `--country` is not given |
| `defaults.gender` | none | The persona gender when `--gender` is not given |

`DISSOLVE_DEFAULT_PERSONA`, `DISSOLVE_DEFAULT_COUNTRY` and `DISSOLVE_DEFAULT_GENDER` override the defaults (the `DESTROY_` names still work). A flag beats the environment, which beats the config file.

## Global flags

| Flag | Does |
|---|---|
| `--api-key` | The API key, over the environment and the config file |
| `--api-url` | The API host (`https://api.dissolve.email`) or base (`https://api.dissolve.email/api`), over `DISSOLVE_API_URL` |
| `--json` | JSON output |
| `--quiet`, `-q` | Minimal output: ids, or the one value asked for |
| `--no-color` | No colour |
| `--interactive`, `-i` | The interactive terminal interface |

Plain `http:` addresses are refused except to localhost, so a key never crosses the network in the clear.

## Output

Plain, coloured, human-readable output is the default and is safe to pipe. `--json` is for `jq` and programs; `--quiet` prints only what a script needs. `-i` turns on styled tables, spinners and progress bars, and `dna tui` opens a full-screen dashboard with Inboxes, Messages and Account tabs.

The interface is chosen in this order: `--json` or `--quiet` always give plain output; `-i` gives the interactive interface; `--no-color` or a set `NO_COLOR` give plain output; `DNA_TUI=0` forces plain and `DNA_TUI=1` forces interactive; otherwise plain.

A command that fails prints the reason and exits with status 1.

## In CI

Make an API key in the app, store it as a secret and expose it as `DISSOLVE_API_KEY`. No `login` step is needed.

```yaml
- name: Sign-up test
  env:
    DISSOLVE_API_KEY: ${{ secrets.DISSOLVE_API_KEY }}
  run: |
    npm install -g @dissolve-email/cli
    ID=$(dna create --ttl 15 --label "ci-$GITHUB_RUN_ID" --json | jq -r .id)
    EMAIL=$(dna get "$ID" --json | jq -r .email)
    npm run test:signup -- --email "$EMAIL"
    CODE=$(dna verify "$ID" --timeout 60 --quiet)
    npm run test:confirm -- --code "$CODE"
    dna delete "$ID"
```

## Coming from the destroy.network CLI

- On first run, `~/.config/dna/config.json` is copied to `~/.config/dissolve/config.json`. The old file is kept, so the old CLI still works. A saved destroy.network API address is replaced by the new default; any other address is kept. Your `sk_live_` key keeps working: keys moved with the accounts.
- `DESTROY_*` environment variables are still read; `DISSOLVE_*` wins when both are set.
- `verify --pattern` now runs locally on the matches the server found; the server no longer takes a regular expression. Use `--from` to filter by sender on the server.
- The npm package is `@dissolve-email/cli` (it was `@buun_group/dna`). The command is still `dna`.

The source and changelog are in the [dissolve-cli repository](https://github.com/dissolve-email/dissolve-cli).
