Skip to main content

CLI Quick Start

Install the elven binary, sign in, run a few commands. ~5 minutes.

Install​

# Global — recommended
npm install -g @elvenvtt/cli

# Or one-off via npx
npx @elvenvtt/cli login

Verify:

elven --version
# → 0.7.1

Sign in​

Two paths.

Browser OAuth (interactive)​

elven login

A browser tab opens at app.elvenvtt.com/cli-auth. Sign in if you aren't already. The page POSTs your session back to a one-shot localhost server the CLI spawned. The CLI saves the credential to your OS keyring (or a chmod-600 file on Unix as a fallback) and exits.

Personal access token (non-interactive)​

For CI, headless environments, or anywhere a browser flow isn't an option, generate a personal access token at app.elvenvtt.com/developer → CLI Tokens → New Token (or run elven tokens create --label "ci" once you've signed in interactively).

# Persist the token
elven login --token el_pat_abcdef...

# Or use the ELVEN_TOKEN env var (no persistence — re-read on every command)
export ELVEN_TOKEN=el_pat_abcdef...
elven whoami

Confirm identity​

elven whoami

Prints your profile, user id, slug, email, and tier claims (admin/vip/pro/beta).

Common commands​

# Browse the marketplace
elven listing list --type app --limit 10

# What have I published?
elven listing mine

# Inspect one listing
elven listing show <listing-id>

# Create a free listing pointing at an externally-hosted bundle
elven listing create --type app --name "My Companion" --manifest-url https://...

# Publish a companion from a project dir (most common — see Publishing)
cd my-companion/
elven publish

# What's in my analytics dashboard?
elven analytics overview

Output formatting​

By default the CLI prints pretty tables when stdout is a TTY and JSON when it isn't:

# Human-readable
elven listing mine

# JSON (forced, even when in a terminal)
elven listing mine --json

# Pipe-friendly — automatically JSON because stdout isn't a TTY
elven listing mine | jq '.[] | .name'

Profiles (multi-account)​

elven login --profile work        # sign in under "work"
elven login --profile personal    # different account
elven --profile work listing mine # use "work" for one command
elven profile use work            # change the default

See Profiles for the full flow.

Next​

  • CLI Reference — every command and flag.
  • Publishing — elven publish + .elven.json schema + GitHub Actions recipe.
  • MCP Setup — same verbs, exposed to AI agents.