Commands

Every command in ven works two ways:

Interactive — run without arguments. Prompts walk you through the form.
Direct — pass positional arguments and flags. No prompts; output is structured (use --json for machine consumption).

Both paths call the same service methods and the same renderers, so the visual output is identical.

Global flags

Flag	Effect
`--api <url>`	Override the auth-server base URL (default `https://new-auth.vendidit.com/api/v1`)
`--app <code>`	Override the app code (default `auth-client-demo`)
`--json`	Emit JSON instead of pretty tables — for piping to `jq`
`-y, --yes`	Auto-confirm destructive prompts
`--no-color`	Disable ANSI colors (also honors `NO_COLOR` env var)
`-h, --help`	Per-command help
`-v, --version`	Print version

Env-var equivalents: VEN_API_URL, VEN_APP_CODE, NO_COLOR.

`ven`

No-args: launches the interactive main menu. Guards on login — if no session is cached, drops into ven login first.

After every menu action, returns to the menu until you pick Exit.

`ven login`

Prompts for email (pre-fills last-known if a previous session existed).
Soft-validates the email format. (@vendidit.com restriction is enforced server-side.)
Prompts for password (masked).
If the server returns { requires_2fa: true }, prompts for a 6-digit TOTP code and retries.

On success: writes ~/.vendidit/session.json (mode 0600), prints:

✓ Signed in as you@vendidit.com · system_admin

`ven logout`

Revokes the current refresh token server-side, then deletes the local session file. No-op if you’re already signed out.

✓ Signed out.

`ven profile`

Pretty-print your profile, roles, permissions (grouped by resource), and organization memberships.

ven profile                # pretty
ven profile --json         # JSON

Sample output:

── Profile ───────────────────────────────────────────────
Name           Demo Test
Email          demotest@vendidit.com
User ID        9c1f-7bc2-…
Status         active
Email verified yes
2FA            disabled
Created        2026-04-12 14:33

── Roles ─────────────────────────────────────────────────
  system_admin

── Permissions ───────────────────────────────────────────
  organizations    · create, delete, read, update
  permissions      · register
  users            · create, delete, impersonate, read, update
  …

── Organizations ─────────────────────────────────────────
  ┌────────────┬──────────────┬──────────┬─────────────────┬──────────────┐
  │ Org        │ Slug         │ Role     │ Joined          │ ID           │
  └────────────┴──────────────┴──────────┴─────────────────┴──────────────┘

`ven users [args...]`

List, search, view, and edit users.

ven users                              # paginated table; interactive selection
ven users ryan@vendidit.com            # search by email (exact preferred)
ven users <uuid>                       # user detail
ven users <uuid> roles system_admin    # set roles directly
ven users <uuid> delete                # hard-delete (--yes to skip confirmation)
ven users --org <orgId>                # scope to a single org
ven users --limit 100                  # adjust page size
ven users --json                       # JSON output

Interactive flow

ven users → optional scope picker (all users vs one org, when you’re system_admin / super_admin) → paginated table → pick a user → user-detail view → action menu:

Edit roles — multi-select checklist of every system role; selection saves via PUT /admin/users/{id}/roles.
Terminate sessions — multi-select from the user’s active sessions.
Revoke ALL sessions — POST /admin/users/{id}/revoke-sessions. Bumps the per-user token-version so outstanding access tokens stop working cross-replica.
Delete user — confirms by requiring you to type the user’s email, then prompts for an audit reason.

Permission gating

system_admin / super_admin → see all users.
org_admin → only their org’s users (scope auto-applied server-side).
Anyone else → “Access denied.”

`ven orgs [args...]`

Browse and manage organizations. system_admin / super_admin only.

ven orgs                       # list all
ven orgs <id>                  # org detail + member table
ven orgs <id> delete           # delete (--yes to skip confirmation)

Interactive flow

ven orgs → paginated list → pick org → org-detail view with members → action menu:

View members — opens the users list scoped to this org.
Delete organization — confirms by typing the org slug.

`ven apps [args...]`

Browse and manage registered apps. system_admin only for mutations.

ven apps                       # list registered apps
ven apps <code|id>             # app detail
ven apps <id> delete           # unregister (--yes to skip confirmation)

ven apps create \
    --code marketplace-v2 \
    --name "Marketplace v2" \
    --description "Public marketplace, browser SPA" \
    --redirect-url https://marketplace-v2.vendidit.com/auth/callback \
    --email-domain vendidit.com \
    --auth-method password --auth-method google \
    --service-code marketplace-v2 \
    --auto-grant

Interactive create

ven apps → + Register a new app walks you through every field with inline validation:

code (kebab-case, validated)
name, description
Allowed redirect URLs (comma-separated)
Allowed email domains
Allowed auth methods (multi-select: password, google, apple, microsoft, github, custom)
Auto-grant on signup (boolean)
Service codes (defaults to [code])

On success: prints the new app’s id + code. On error: surfaces the server’s error.code + error.message so you can fix the field and retry.

See App registration for what each field means.