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:

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. 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 runs it as a background task its harness tracks; 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: 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.

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.

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

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.