# 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. `-scaffold` creates the app from a
  published Elements app instead of the built-in templates, for example
  `-scaffold=elementscode/scaffold-ecommerce`; see `elements man start/layout`. Has
  subcommands; see `elements create --help`.
- `elements start`: start and run your program, the same way in development and
  production. It exits when the program exits, with the program's exit code;
  `-repl` keeps it running and runs the program again on the next build, for a
  script you are editing and re-running. An agent may run it with `&` so the
  user can see the app; see `elements man build`. In development it opens the
  app in the user's browser once per process, and skips that inside an agent
  app that shows pages itself. `ELEMENTS_NO_BROWSER=1` forces the skip, and an
  explicit `ELEMENTS_NO_BROWSER=0` opens the browser even in one of those.
- `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` (`i`): install everything `config.jsoc` declares, then
  rebuild. This is the command to run after editing the dependency list by hand.
- `elements install <pkg>`: add a package at its latest version and rebuild
  against it. `<pkg>@1.2.3` pins one version, `<pkg>@^1.2.0` takes a range, and
  `<pkg>@latest` follows the tag.
- `elements install -u`: upgrade each package to the newest version its spec
  allows. Without it an existing resolution is reused from `package.lock`, so a
  build stays on the versions it was tested against.
- `elements install -f`: ignore the lock and resolve every dependency again.
  This can move packages you did not ask about, so reach for a version spec
  first.
- `elements install -d` / `-p`: install as a dev or peer dependency.
- `elements uninstall <pkg>`: remove a package.

Specs live in `config.jsoc` and the versions they resolve to are written to
`package.lock`. An install that cannot resolve a package prints the reason and
exits non-zero, and neither file is touched. Full topic, including local
packages: `elements man packages`.

**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>"` (`-c`): run a single SQL statement and exit
  (equivalent to `psql -c "<stmt>"`). Same on `elements db shell -sql "<stmt>"`.
  Add `-json` for the rows as JSON; put psql options after `--`
  (`elements db -sql "select 1" -- -At`).
- `elements db < file.sql`: run a SQL file as a script.
- `elements db migrate` (`m`): apply pending migrations on demand.

**Deployment**
- `elements deploy`: deploy the project. Full topic: `elements man deploy`.
- `elements ssh`: open a shell on a deploy machine, in the app at `/elements/app`.

**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

`-remote=[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 -remote                       # query the production server's build state
elements build -remote=staging               # query the staging server
elements db -remote=production#production1   # psql against a specific machine
elements ssh -remote=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`.