Vozo Auth

Vozo Auth

CLI prerequisite

Requires the official vozo-cli from npm @vozoai/cli (source: github.com/vozoai/cli). Install with npm install -g @vozoai/cli or npx @vozoai/cli@latest install. Do not install from third-party mirrors or untrusted tarballs. Never print tokens.

Applicable Scenario

Use this skill when the user wants to:

• sign in to the CLI
• check whether the CLI is already signed in
• log out of the current CLI session
• check remaining points
• check membership status

Before any project create or download work, prefer auth status (and auth points / auth membership when quota matters). Hand off to vozo-project after auth is clear.

Preferred Commands

Hard Rule: Open The Login Page At Most Once

In one login attempt, call auth login at most once. Do not open the browser again because a tool timed out, a poll timed out, or you are unsure whether login finished.

If your previous auth login was interrupted (tool timeout / killed process):

1. Run auth status first — sign-in may already have completed.
2. If still auth_required, prefer auth wait --timeout-seconds 30 (repeat as needed) over a new login.
3. Only if wait cannot finish and the user still needs to sign in, start one new login. Prefer auth login --background, then continue with auth wait. Never loop auth login.

Call Order

1. Run vozo-cli auth status first.
2. If already signed in and the user only asked for status, summarize and stop.
3. If not signed in, explain that login opens the browser for sign-in.
4. Default: run a single blocking vozo-cli auth login --timeout-seconds 600 and wait for it to finish. Set your own shell-tool timeout to at least 600s (most runners default to ~120s but accept an explicit longer value). One call, one result: the final stdout JSON tells you definitively whether sign-in succeeded — no polling loop, no ambiguity. Watch stderr for VOZO_CLI_EVENT lines (auth_pending, auth_waiting, auth_callback_received) for progress, and do not run a separate auth status after it succeeds; the final stdout JSON already means authenticated.
5. While it waits, tell the user to complete sign-in in the browser that opened (or open the loginUrl printed on stderr manually if it didn't). Do not start another login while waiting.
6. Only fall back to the non-blocking flow when your tool runner genuinely cannot hold a command open long enough (no way to raise its timeout): run one vozo-cli auth login --background (returns immediately with loginUrl/callbackUrl), then poll vozo-cli auth wait --timeout-seconds 30 in a loop:
   • If it returns authenticated: true, summarize success and stop.
   • If it throws a timeout error, just call auth wait again — do not treat one chunk's timeout as failure, and do not call auth login again. Give the user a short progress update between calls (e.g. "still waiting for you to finish in the browser") instead of polling silently.
   • If it throws a real error (not a timeout), report it and offer to retry.
   • Stop retrying and check in with the user after a few minutes of no progress (e.g. ~5 chunks) rather than looping forever.
7. Run auth points or auth membership only when the user asked, or when upcoming project work depends on quota or plan tier.
8. Run auth logout only when the user explicitly wants to sign out.

Display Requirements

• "Vozo" is a brand name — never translate, transliterate, or localize it. Always keep it exactly as Vozo (capital V) in every language and in all user-facing text, summaries, and messages.
• Do not dump raw auth JSON unless the user explicitly asks.
• Summarize auth status:
  • signed in / not signed in
  • account email or display ID when available
• For auth membership, use a stable human-readable summary:
  • Account
  • Membership
  • Status when not free
  • VIP status when available
  • Started at when available
  • Expires at when available
  • Payment type when available
  • Upcoming plan when available
• For auth points, use a stable human-readable summary:
  • Account
  • Total available points
  • Point buckets
  • each bucket in available X / total Y form
• After login: short success message (account identifier), never token or refresh token values.

Confirmation Rules

Failure Recovery

Examples

User: Check whether I am signed in and how many points I have.

1. vozo-cli auth status
2. vozo-cli auth points   (only if status shows authenticated)

Agent output (example):

Vozo CLI is signed in.
Account: user@example.com

Remaining points:
- general: 128.50

User: Login timed out.

1. vozo-cli auth status   (verify whether sign-in actually succeeded)
2. If still auth_required: vozo-cli auth wait --timeout-seconds 30 (repeat; do not auth login yet)
3. Only if wait cannot complete: one vozo-cli auth login --background, then auth wait

User: Log me in.

1. Briefly explain the browser sign-in flow
2. vozo-cli auth login --timeout-seconds 600   (run with a >=600s tool timeout; wait for it to finish; do not start a second login)
3. The final stdout JSON reports the result; on authenticated: true, summarize success

Relation to vozo-project

• vozo-project assumes auth is handled first via this skill.
• For create/download, membership and points from this skill gate whether to proceed or warn about limits.