@elvenvtt/cli

The elven command-line interface for Elven creators. Manage listings, posts, drops, follows, and analytics from the terminal. Includes a one-command elven publish flow for shipping companion apps.

Full docs: docs.elvenvtt.com/docs/agent-platform

npm install -g @elvenvtt/cli
elven login
elven listing mine

Install

# Global (recommended — `elven` everywhere)
npm install -g @elvenvtt/cli

# Or per-project / one-off
npx @elvenvtt/cli login

Commands

Auth

| Command | Description | |---|---| | elven login | Browser sign-in. Opens your default browser; a loopback server catches the session. | | elven login --token el_pat_xxx | Non-interactive sign-in via personal access token. | | elven logout | Clear stored credentials for the active profile. | | elven whoami | Show the active profile + identity. |

Listings

| Command | Description | |---|---| | elven listing list | Browse public listings (no auth). | | elven listing mine | List your own listings (includes drafts). | | elven listing show <idOrSlug> | Show details for one listing. | | elven listing create --type app --name "..." --manifest-url "..." | Create a listing. | | elven listing update <id> --status active | Update fields. | | elven listing delete <id> | Delete (your own only). |

Publish

| Command | Description | |---|---| | elven publish | Build, deploy, and sync a companion from a project dir with .elven.json. |

Posts

| Command | Description | |---|---| | elven post new --title "..." --body @./post.md | Create a post (draft by default). | | elven post list [--user <id>] | List a user's posts (defaults to yours, includes drafts). | | elven post show <id> | Show a single post. | | elven post update <id> --status published | Update fields. | | elven post delete <id> | Delete (your own only). |

Drops

| Command | Description | |---|---| | elven drop create --name "..." --open +0h --close +7d --listings <id1>,<id2> | Create a drop. | | elven drop list [--user <id>] | List drops by user. | | elven drop show <id> | Show a drop + your claim/eligibility state. | | elven drop update <id> --close +14d | Update fields. | | elven drop delete <id> | Delete (your own only). | | elven drop claim <id> | Claim a drop (must be eligible + inside window). | | elven drop feed | Currently-open drops from creators you follow. | | elven drop claims | Drops you have claimed. |

--open / --close accept: ISO 8601 (2026-06-01T00:00:00Z or 2026-06-01), relative (+30d, +12h, +90m), or epoch ms.

Followers

| Command | Description | |---|---| | elven follower count <userId> | Get a public follower count. | | elven follower following | List creators you follow. | | elven follower follow <slug> | Follow a creator by slug. | | elven follower unfollow <id> | Unfollow by creator id. |

Analytics

| Command | Description | |---|---| | elven analytics overview | Followers + subscribers + drops + recent activity. | | elven analytics sales | Sales totals, top listings, recent purchases. |

Tokens (personal access tokens)

| Command | Description | |---|---| | elven tokens create --label "ci-publishing" [--expires-in-days 90] | Create a PAT (returned once — copy it). | | elven tokens list | List your PATs (no plaintext). | | elven tokens revoke <id> | Revoke a PAT. |

Profiles (multi-account)

| Command | Description | |---|---| | elven profile list | Show all stored profiles. | | elven profile use <name> | Switch the default profile. |

Flags

| Flag | Effect | |---|---| | -p, --profile <name> | Override the active profile for one command. | | --json | Force JSON output. By default JSON is on when stdout is not a TTY (CI, pipes) and a pretty table otherwise. | | -V, --version | Print version. | | --help | Print help (elven <cmd> --help for command-specific). |

Exit codes

Stable across versions. CI scripts can branch on these.

| Code | Class | Meaning | |---|---|---| | 0 | OK | Success. | | 60 | AUTH | Not signed in / token expired / token revoked. | | 70 | API | Server returned 4xx/5xx with a body. | | 80 | USAGE | Bad input (missing required flag, malformed value). | | 90 | NETWORK | Could not reach the server. | | 1 | UNKNOWN | Anything else (treat as a bug — file an issue). |

Auth

elven login runs a browser OAuth flow:

1. Spawns a local HTTP server on a random port.
2. Opens your browser to https://app.elvenvtt.com/cli-auth?cb=…&state=….
3. You sign in to Elven (if not already).
4. The page POSTs your session back to the loopback.
5. The CLI saves it via your OS keyring (or ~/.elven/credentials with chmod 600 on Unix as a fallback).

For CI / headless / agent environments: create a personal access token at app.elvenvtt.com/developer under the CLI Tokens tab and either:

• Run elven login --token el_pat_xxx once to persist it, or
• Set ELVEN_TOKEN=el_pat_xxx in your environment (no persistence — every command re-reads the env var).

Profiles

You can have multiple Elven identities on one machine. Each profile holds its own credentials.

elven login --profile work        # sign in under "work"
elven login --profile personal    # a different identity
elven --profile work listing mine # use "work" for this one command
elven profile use work            # set "work" as the default

elven publish

The one-command "ship a companion" flow. From a project directory containing .elven.json:

{
  "type": "app",
  "name": "Lancer",
  "build": {
    "outputDir": "dist",
    "command": "node build.cjs",    // default if build.cjs exists; else `npm run build`
    "manifestFile": "marketplace.json"
  }
}

Then:

elven publish

This:

1. Runs the project's build (skip with --no-build).
2. On first publish, creates the listing and writes its id back to .elven.json.
3. Walks build.outputDir and uploads every file to the Elven CDN (skip with --no-deploy).
4. Flips the listing to status=active with a fresh manifestUrl.

After this, the companion is installable from /c/{your-slug}.

Library use

The CLI is a thin wrapper over @elvenvtt/api. If you want to script Elven from your own Node code without the CLI binary, install that directly.

The CLI also exports two subpaths for advanced consumers (the MCP server uses them):

• @elvenvtt/cli/storage — the keyring-backed token store.
• @elvenvtt/cli/publish — the runPublish function from elven publish.

Security

PATs are long-lived credentials. Don't commit them to source control; use ELVEN_TOKEN env var instead of inline config. Audit + revoke from Studio Developer → CLI Tokens — each token now tracks last-used time and IP. Full guidance at docs.elvenvtt.com/docs/agent-platform/security.

License

MIT.