vector-cli-usage

name	vector-cli-usage
description	Explain how to use the installed Vector CLI in this repository. Use when users ask for CLI onboarding, command examples, auth/profile/org workflows, scripting guidance, or a detailed explanation of how to operate `vcli` after installation.

Vector CLI Usage

Use this skill when the user wants an explanation of the installed Vector CLI, not when they want new CLI features implemented.

This skill is for answering questions like:

• "How do I use the Vector CLI?"
• "Explain the CLI commands"
• "How do auth, profiles, and org selection work?"
• "What commands should I run after installing the CLI?"
• "How do I script the CLI with --json?"

Verify The Current CLI First

Do not rely on stale command memory. Before giving a detailed answer, verify the current branch's CLI surface from:

• packages/vector-cli/src/index.ts
• packages/vector-cli/src/auth.ts
• packages/vector-cli/src/session.ts
• packages/vector-cli/src/index.test.ts
• packages/vector-cli/src/auth.test.ts

Prefer checking the real help output:

pnpm exec tsx packages/vector-cli/src/index.ts --help
pnpm exec tsx packages/vector-cli/src/index.ts auth --help
pnpm exec tsx packages/vector-cli/src/index.ts request --help
pnpm exec tsx packages/vector-cli/src/index.ts work --help
pnpm exec tsx packages/vector-cli/src/index.ts task --help

If the user is using the installed binary instead of the repo entrypoint, mirror the same examples with:

vcli --help
vcli auth --help

Use whichever form matches the user's setup:

• Repo-local examples: pnpm exec tsx packages/vector-cli/src/index.ts ...
• Installed binary examples: vcli ...
• Installed package name: @rehpic/vcli

What To Explain

When the user asks for a detailed explanation, structure the answer in this order:

1. What the CLI talks to
2. How auth and session storage work
3. How org context works
4. The main command groups
5. Common end-to-end workflows
6. Scripting and troubleshooting notes

Keep examples concrete and copy-pasteable.

Core Concepts

App URL and Convex URL

The CLI uses:

• --app-url for the Next.js app and Better Auth routes
• --convex-url for the Convex deployment

The app URL must come from:

• --app-url <url>
• the saved profile session
• NEXT_PUBLIC_APP_URL

Convex URL is resolved in this order:

• --convex-url flag
• saved profile session
• NEXT_PUBLIC_CONVEX_URL or CONVEX_URL env vars
• auto-fetched from the app via GET <app-url>/api/config (returns { convexUrl })
• fallback: http://127.0.0.1:3210

In most cases the user only needs to provide --app-url and the CLI resolves the Convex URL automatically. The resolved URL is cached in the profile session.

If the local app origin is not already stored in the profile, say that explicitly and show --app-url.

Profiles

Profiles let one machine keep separate CLI sessions.

Session files are stored in:

~/.vector/cli-<profile>.json

Recommend:

• default for normal use
• named profiles like work, staging, or demo for parallel environments

Examples:

vcli --profile work auth login [e-mail] --password 'secret'
vcli --profile staging --app-url http://localhost:3001 auth whoami

Org Context

Most workspace commands need an active org.

The user can:

• pass --org <slug> on each command, or
• set an active org once with org use <slug>

Explain this clearly because many commands fail without org context.

For agent-managed Requests and Work, do not silently rely on the active org. Resolve the workspace from the Vector URL, the user's explicit choice, or the workspace that uniquely contains the referenced key, then pass --org <slug> on every related read and mutation. If a new Request could belong to multiple workspaces, ask instead of choosing the last active org.

Auth Workflow

Explain auth with these commands first:

vcli auth signup --email [e-mail] --username yourname --password 'secret'
vcli auth login [e-mail] --password 'secret'
vcli auth whoami
vcli auth logout

Notes to include:

• Signup uses email, username, and password.
• Login accepts either email or username as the identifier.
• whoami shows the current user, org memberships, and active org.
• Logout clears the stored session for the selected profile.

If the user wants a first-run walkthrough, recommend:

vcli auth signup ...
vcli org create --name "Acme" --slug acme
vcli org use acme
vcli auth whoami

Main Command Groups

Mention command groups in practical terms instead of listing them with no context.

Workspace And Discovery

• org
• invite
• search
• refdata
• permission
• activity
• notification

Settings And Metadata

• role
• priority
• state
• status
• presence

Core Entities

• request — define an expected output, route or claim it, link it to Work, and close the requester review loop
• work — hold one or more requests, start intentionally, publish context, pause/block, raise review, and hand off ownership
• task — track the concrete steps inside Work, including agent-attributed creation and status updates
• team
• project
• issue — legacy compatibility; prefer Request, Work, and Task for new workflows
• document
• folder

Platform Admin

• admin

Call out that admin commands require platform-admin privileges.

Common Workflows To Show

1. Create And Work Inside A New Org

vcli auth signup --email [e-mail] --username you --password 'secret'
vcli org create --name "Acme" --slug acme
vcli org use acme
vcli team create --key eng --name "Engineering"
vcli project create --key api --name "API" --team eng
vcli --org acme request create --title "Ship CLI" --expected-output "A reviewed CLI release"
vcli --org acme request claim REQ-1
vcli --org acme work create --title "Ship CLI" --request REQ-1
vcli --org acme work start WORK-1
vcli --org acme task create WORK-1 --title "Implement command surface"

2. Invite Another User

vcli org invite acme --email [e-mail]
vcli invite list
vcli invite accept <inviteId>

Explain that invite acceptance happens from the invited user's profile/session.

3. Inspect Workspace Metadata Before Writing Commands

vcli refdata acme
vcli search --org acme "billing"
vcli permission check issue:create --org acme

Use this workflow when the user wants to discover valid project keys, members, states, priorities, or permissions before mutating data.

4. Script The CLI

Recommend --json for automation:

vcli --json issue list --org acme
vcli --json notification inbox --filter unread

For an agent that needs to wait for Work to change, use the real-time watcher. Global --json produces one NDJSON object per event:

vcli --json work watch API-1 --events tasks,requests --once --timeout 1800

Available categories are work, tasks, requests, attention, handoffs, and executions. Use --initial to emit the current snapshot before changes.

If the user is scripting, mention:

• prefer --json
• prefer explicit --profile
• prefer explicit --org

Important Behavior Notes

• org members uses the roles-aware member query and includes custom-role state.
• Auth is session-based and profile-scoped.
• Some commands need an org slug even if the user is logged in.
• Team and project keys are validated by the backend; recommend short slug-like keys.
• Platform admin commands are separate from normal org-admin commands.

Troubleshooting Guidance

When troubleshooting, start from the actual error and map it to the likely fix:

• Not logged in Run vcli auth login or vcli auth signup.

• app URL is required Pass --app-url <url>, set NEXT_PUBLIC_APP_URL, or log in once with --app-url so the selected profile stores it.

• Organization slug is required Pass --org <slug> or run vcli org use <slug>.

• Auth errors against the wrong server Make sure --app-url matches the running app origin.

• Convex connection errors Verify NEXT_PUBLIC_CONVEX_URL or pass --convex-url.

• Validation errors on create/update commands Check keys, slugs, required options, and org context. Suggest refdata or search first.

Response Style For This Skill

When answering with this skill:

• Prefer installed-binary examples if the user says the CLI is installed.
• Prefer repo-entrypoint examples if the user is developing inside this repo.
• Group commands by workflow, not by file.
• Include exact commands, not pseudocode.
• Mention --json, --profile, and --org whenever they materially improve the workflow.
• If the user asked for a "detailed explanation", include both concept-level explanation and concrete examples.