# 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`:

```bash Terminal
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`. A
  new app starts as a git repository when git is installed and the app is not
  inside another repository; `-no-git` skips it. Once the first install has
  written `package.lock`, the project server commits everything create made as
  `elements create <name>`, with your git `user.name` and `user.email`, so the
  first diff shows only your own changes. It does this only while the
  repository has no commits, and skips it when no identity is set. 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.
  The user runs it, not an agent; see `elements man build`. In development it
  opens the app in the user's browser once per process, or in the editor's own
  browser from a VS Code terminal with the Elements extension.
  `ELEMENTS_NO_BROWSER=1` skips it.
- `elements kill`: stop the project: the app, its jobs, the project server,
  and any `elements start` attached to it, which exits. `-destroy` also drops
  the project's app and test databases and their backups, for a project folder
  you are about to delete. The folder itself is left alone.

**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. It
  exits with the program's exit code, or 1 when the build has errors and
  nothing ran.
- `elements logs`: what the app logged, read from `.elements/logs`, every
  service merged in time order. `-service app` keeps one service, `-f` follows,
  `-since 10m` and `-until <time>` take a duration back from now or a time, and
  `-json` prints the records as stored, one JSON object per line. `-remote`
  reads the deploy machines' journals instead. Full topic: `elements man logs`.

**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 licenses`.
- `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, with no
  spinner and no full-screen view, in a terminal or out of one. The commands
  with a JSON form are `build`, `test`, `create`, `install`, `uninstall`,
  `migrate`, `db` (with `-sql`, and its `create`, `drop` and `reset`) and
  `deploy`; an agent passes it to those. On `start` and `run` it only drops
  the terminal UI. `config` always prints JSON.
  Without it, a terminal gets the interactive views and anything else (a pipe,
  a file) gets plain text.
- `-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`.

```bash Terminal
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
elements logs -remote -f                     # follow every production machine's logs
```

Every command that talks to the project server takes `-remote` and works the
same against a deploy machine as it does locally.

## The Project Server

Project 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`.