elements
Manual CLI

CLI

elements man cli Read as markdown

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

-c / --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.