# CLI

The `elements` command-line interface. One binary, a handful of subcommands,
consistent conventions across all of them.

## Discovering Commands

Every command has its own help screen. Run the command with `-h` or `--help`:

```
elements --help              # top-level commands and global options
elements create --help       # create's subcommands, arguments, options
elements build --help        # build's flags
elements db --help           # db's subcommands
```

Help output is short and self-contained. Read the whole thing. Don't pipe
through `head`, `tail`, or `less`: truncating the output hides subcommands and
options you'll need. If the screen is taller than your terminal, scroll. The
output is not paginated.

## Top-Level Commands

Grouped by purpose:

**Project lifecycle**
- `elements create` (`c`): scaffold a new app, package, page, template,
  migration, job, email, test, or config files. Has subcommands; see
  `elements create --help`.
- `elements start`: start and run your program, the same way in development and
  production. An agent may run it with `&` so the user can see the app; see
  `elements man build`.
- `elements kill`: stop the project server.

**Build, test, run**
- `elements build` (`b`): query the current build state. `-json` for structured
  output. Full topic: `elements man build`.
- `elements test` (`t`): query test results. `-json` for structured output. Full
  topic: `elements man tests`.
- `elements run` (`r`): run a one-off program once. Useful for scripts.

**Packages and dependencies**
- `elements install <pkg>` (`i`): add a package and rebuild against it.
- `elements uninstall <pkg>`: remove a package.

**Database**
- `elements db` (`d`): manage the project database. Has subcommands for migrate,
  shell, create, drop, reset, and dump. Full topic: `elements man database/cli`.
- `elements db -sql "<stmt>"`: run a single sql statement and exit (equivalent
  to `psql -c "<stmt>"`). Same on `elements db shell -sql "<stmt>"`.
- `elements db migrate` (`m`): apply pending migrations on demand.

**Deployment**
- `elements deploy`: deploy the project. Full topic: `elements man deploy`.
- `elements ssh`: open an SSH session to a deploy machine.

**Docs and config**
- `elements man <topic>`: open a documentation topic.
  `elements man -s <words...>` fuzzy-searches the whole corpus.
- `elements config`: print the resolved project config.

**Account**
- `elements upgrade`: upgrade the elements toolchain.
- `elements purchase`: open the purchase page in your browser. Full topic:
  `elements man purchase`.
- `elements license` (`l`): manage your per-machine license. Full topic:
  `elements man licenses`.

Run a program once with `elements run <path>` (e.g.
`elements run app/scripts/seed.ts`). A bare path is not a command. An
unrecognized first word is reported as an error rather than run.

## Conventions

A few flags and patterns repeat across every command:

- `-h` / `--help`: show the help screen for that command.
- `-v` / `--version`: print the version.
- `-q` / `--quiet`: suppress progress output (useful in scripts and CI).
- `-json`: emit structured JSON instead of human-readable text. Available
  wherever output is queryable (`build`, `test`, `config`, `deploy`, etc.).
  Ideal for agents.
- `-path=<path>`: run against the project at `<path>` instead of the current
  directory. Handy when driving `elements` from outside the project root.
- `-force` / `-f`: bypass a confirmation prompt or idempotency check. Used on
  commands like `elements db reset -force` and `elements create -force`. A
  fail-safe the user opts into when they explicitly want the destructive or
  override behavior.

Short and long forms are interchangeable. Options can appear before or after
positional arguments.

## Connecting to a Deploy Machine

`--connect=[env]` connects the command to a deploy machine instead of
running locally. `env` defaults to `production`. Target a specific machine with
`env#machine`.

```
elements build -c                    # query the production server's build state
elements build -c staging            # query the staging server
elements db -connect=production#production1   # psql against a specific machine
elements ssh -c staging              # open an SSH session to staging
```

Most commands work the same locally and remotely.

## The Project Server

Most commands talk to a long-running project server that started lazily on the
first command and stays running between commands. `elements build`,
`elements test`, and `elements start` are all clients of the same server. State
is cached across clients, so a second query returns immediately. Idle servers
shut themselves down after a period; you can also `elements kill` explicitly.
Full topic: `elements man build`.