Scripting

ven is built so every command runs cleanly without prompts when you supply enough arguments. Combined with --json for output and --yes for destructive ops, you get a real scripting surface.

---

The pattern

Mode	Trigger
Interactive	Run with no args, or with a partial set of args. ven prompts for the rest.
Direct	Pass positional args + flags. ven skips prompts; output is structured.
Non-interactive destructive	Add --yes (or -y). Skips confirmation prompts. (hard-delete still requires a typed reason — pass via --reason once that flag lands.)

---

Pipe-friendly output

# All users → JSON → suspended ids
ven users --json | jq -r '.[] | select(.status=="suspended") | .id'

# List apps as a TSV
ven apps --json | jq -r '.[] | [.code, .name, .status] | @tsv'

# Profile claim → roles array
ven profile --json | jq -r '.roles | join(",")'

---

Common ops scripts

Register a new app on first deploy

ven apps create \
    --code "$APP_CODE" \
    --name "$APP_NAME" \
    --redirect-url "https://$APP_DOMAIN/auth/callback" \
    --auth-method password --auth-method google \
    --auto-grant \
    --json | tee -a apps.log

Bulk-set roles for a list of user ids

xargs -I {} ven users {} roles base_user seller < user-ids.txt

Each invocation pays a small cold-start (~150 ms). For very large batches, prefer one of the bulk admin endpoints directly.

Sweep suspended accounts

ven users --json \
  | jq -r '.[] | select(.status=="suspended") | .id' \
  | xargs -I {} ven users {} delete --yes

---

Authentication for scripts

ven reads tokens from ~/.vendidit/session.json — the same place interactive runs use. There’s no separate “service account” mode yet. Two practical patterns:

1. Run ven login once on the box, then schedule cron jobs that reuse the same session file. The SDK refreshes automatically.
2. Use an m2m_client token (see auth-server’s OAuth2 client_credentials grant) when the script lives outside an interactive developer’s machine. For now, you’ll need to wire that token into Authorization headers via direct REST — first-class ven m2m:get-token support is on the roadmap.

---

Exit codes

Code	Meaning
0	Success
1	Command threw — see stderr for the message
130	User cancelled (Ctrl-C / Esc) during an interactive prompt

Scripts should branch on non-zero and bubble up the stderr message — ven already surfaces the server’s error.code / error.message rather than a stack trace.