Skip to content
docs
Browse the docsCLI

Tools

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.

dna makes agent identities 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

npm install -g @dissolve-email/cli

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

Shell
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 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 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 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.
CommandDoes
dna auth loginSigns in through the browser and saves a key
dna auth statusShows whether a key is set, where it came from (masked) and the API address
dna auth logoutRemoves the saved key from the config file
dna accountYour plan, key and identity counts and rate limit

Commands

CommandDoes
dna createMakes 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 configReads and writes the config file
dna tuiA full-screen dashboard
dna completion <shell>Shell completions for bash, zsh and fish

create

Shell
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"
FlagDefaultDoes
--ttlthe plan's defaultMinutes until it expires
--prefixrandomStart of the address (letters and digits)
--domainthe default domainA receiving domain
--labelnoneWhat it is for
--password-length16Length of the generated password
--personaoffAlso make a fictional person: name, address, phone, birthday
--no-personaoffSkip the persona even when the config turns it on
--countryrandomThe persona's country: US, UK, AU, CA, DE, FR, JP, BR, IN, ES, IT, NL, KR, MX, SE, PL or NZ
--genderrandomThe persona's gender: male or female

The password is printed when the identity is made: keep it, or save it in the vault. With --quiet only the address is printed.

extend

Shell
dna extend "$ID" --ttl 120          # expires 120 minutes from now
dna extend "$ID" --label "renamed"
FlagDoes
--ttlMinutes from now until it expires, within the plan's longest inbox life
--labelA new label

delete

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

messages, message and wait

Shell
dna messages "$ID"
dna message "$ID" "$MESSAGE_ID"
dna message "$ID" "$MESSAGE_ID" --html
dna wait "$ID" --timeout 60
FlagCommandDefaultDoes
--htmlmessageoffShows the HTML body instead of the text
--timeout, -twait30Seconds to wait, capped by the plan (Pro 30, Business 120)

verify

Shell
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
FlagDefaultDoes
--timeout, -t0Seconds to wait for a code, capped by the plan
--fromnoneOnly mail whose sender contains this text, checked by the server
--pattern, -pnoneA 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 explains what counts as a code.

config

Shell
dna config list
dna config get defaults.country
dna config set defaults.persona true
dna config unset defaults.country
KeyDefaultDoes
api_keynoneThe saved API key
api_urlhttps://api.dissolve.email/apiThe API address
defaults.personafalseMake a persona on every create
defaults.countrynoneThe persona country when --country is not given
defaults.gendernoneThe 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

FlagDoes
--api-keyThe API key, over the environment and the config file
--api-urlThe API host (https://api.dissolve.email) or base (https://api.dissolve.email/api), over DISSOLVE_API_URL
--jsonJSON output
--quiet, -qMinimal output: ids, or the one value asked for
--no-colorNo colour
--interactive, -iThe 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.

Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown