elemnt CLI

The official command-line interface for the Elemnt processing platform — scaffold modules, dry-run them locally, sign in, and (soon) publish them to the cloud registry, all from your terminal.

Built for both humans and AI agents: every command supports --json for machine-readable output, so it plugs straight into Claude Code, Cursor, or any agent that shells out.

The CLI is written in Go (Cobra); the modules it scaffolds and runs are Python (module.py + a module.yaml contract + the elemnt SDK).

Commands

Command	Status	Description
elemnt auth login	✅	Sign in via your browser (OAuth 2.0 + PKCE, loopback)
elemnt init <name>	✅	Scaffold a new module folder
elemnt module pull <example>	✅	Download a ready-to-run example (offline)
elemnt test --dry	✅	Dry-run a module against a simulated worker env
elemnt module register	🟡	Validate + package a module (upload pending)
elemnt module list	🟡	List your registered modules (registry pending)

init and test are top-level aliases of elemnt module init / elemnt module test.

Install

One-liner (recommended):

curl -fsSL https://raw.githubusercontent.com/elemnt-earth/elemnt-cli/main/install.sh | sh

The script checks that go is installed, runs go install into $GOPATH/bin, and prints PATH instructions if needed.

Manual:

go install github.com/elemnt-earth/elemnt-cli/cmd/elemnt@latest

From source (contributors):

git clone https://github.com/elemnt-earth/elemnt-cli.git
cd elemnt-cli
make install        # installs to $(go env GOPATH)/bin
elemnt --version

Make sure $(go env GOPATH)/bin is on your PATH, then elemnt --help works from anywhere.

Quick start

elemnt auth login                 # sign in (opens your browser)
elemnt module pull buffer         # grab a runnable example
cd buffer
elemnt test --dry \               # run it locally
  --input collection_id=places \
  --input buffer_distance=500

Authentication

elemnt auth login runs the OAuth 2.0 authorization-code + PKCE flow with a loopback redirect (RFC 8252):

1. opens your browser to the platform sign-in page,
2. captures the result on a temporary http://127.0.0.1:<port>/callback,
3. exchanges the code for tokens using PKCE (S256),
4. stores them under your user config dir with 0600 permissions:
   • macOS: ~/Library/Application Support/elemnt/credentials.json
   • Linux: ~/.config/elemnt/credentials.json

The stored file holds access_token, refresh_token, and expires_at.

For AI agents (--json)

Add --json to any command for a stable, machine-readable envelope on stdout. Exactly one JSON object is printed per invocation:

// success
{ "ok": true,  "data": { /* command-specific */ } }
// failure (process exits non-zero)
{ "ok": false, "error": { "code": "error", "message": "..." } }

Example:

$ elemnt module pull --list --json
{
  "ok": true,
  "data": { "examples": ["buffer"] }
}

Notes for non-interactive / agent use:

• In --json mode a module's own stdout (from test --dry) is redirected to stderr, so stdout is always a single clean JSON object.
• Errors are emitted as the {"ok":false,…} envelope on stdout and the process exits 1.

Writing a module

A module is a folder with module.py, module.yaml, requirements.txt, README.md, and .gitignore. elemnt init <name> scaffolds all of them.

module.yaml is the contract between the module and the worker runtime (name, version, entry, inputs[], outputs[]). module.py uses the elemnt SDK (pip install elemnt-sdk):

from elemnt import elemnt

def main():
    collection_id = elemnt.GetParameter(0)   # read inputs by order
    gdf = elemnt.get_data(collection_id)      # query the datastore
    gdf = gdf.to_crs(32647)
    gdf["geometry"] = gdf.geometry.buffer(500)
    elemnt.result(gdf.to_crs(4326))           # emit a feature output

if __name__ == "__main__":
    main()

elemnt test --dry stages a temporary JOB_DIR (input/, output/, _params.json, _outputs.json), runs python <entry>, and reports the produced outputs — warning if a declared output was not produced. Inside this monorepo it auto-discovers elemnt-sdk/src for import elemnt; elsewhere, pip install elemnt-sdk (or pass --pythonpath).

Global flags

Flag	Description
--json	Machine-readable JSON output (every command)
-h, --help	Help for any command
-v, --version	Print version

Development

make build     # build into ./bin/elemnt
make test      # go test -race ./...
make tidy      # go mod tidy
make fmt vet   # formatting + static checks
make run ARGS="auth login"

Layout

elemnt-cli/
├── cmd/elemnt/             # main entry point (version via ldflags)
├── internal/
│   ├── command/            # cobra commands: root, auth, init, module, pull, test, register, list
│   ├── output/             # --json envelope helper
│   ├── scaffold/           # module scaffolding + embedded templates
│   ├── manifest/           # module.yaml load + validation
│   └── dryrun/             # local dry-run (simulated worker)
├── examples/               # bundled runnable examples (embedded)
├── docs/                   # design notes / flows
├── install.sh · Makefile · go.mod