Connect through the CLI

Use this path only when the setup guide selected a terminal that can install and run tools in the customer's persistent environment. A temporary chat sandbox is not such an environment.

Locate vf, then run vf version and vf auth login --help. The tested baseline is 0.287.0, with --agent-mode, --no-browser, --login-timeout, and workspace list. Retain a newer compatible installation. If an existing version lacks these capabilities, explain the needed upgrade; preserve its location and do not overwrite an unrelated executable.

If absent, use the verified CLI installer. Use its returned absolute binary path for the rest of this session if it is not on PATH.

Make this live read:

vf workspace list --agent-mode --no-interactive --timeout 20s --color never -o toon

Do not use whoami or stored credentials as proof of connection. Do not print workspace details unless asked. An empty list is a connected account, not a reason to create a workspace. Classify failures before acting:

Use TOON for this read on CLI 0.287.0. Its JSON passthrough can produce empty output when a timeout cancels the response before the body is consumed; TOON uses the fully decoded response. Empty output is not an empty workspace list.

• Missing/expired authentication or HTTP 401: continue to browser sign-in.

• HTTP 403: explain insufficient access; repeated login is not a permission fix.

• Network, rate limit, or service failure: retry a read once after a short indicated delay, otherwise report the blocker. Do not erase credentials.

• Invalid response or missing command: inspect help and the failure; do not claim connected.

The optional connection checker makes this read without printing its body when Python 3.10+ is already available. It parses the complete JSON response on stdout and bounds the entire subprocess to 25 seconds, omitting the CLI's inner timeout to avoid the body-cancellation issue. Truncated, malformed, or stderr-only responses never count as connected. It does not install, log in, or repair anything.

Sign in only if needed

Run as a background task with a bounded 15-minute lifetime. Read JSON events from stderr while it runs:

vf auth login --agent-mode --no-browser --login-timeout 15m

Show the exact authorization_url from awaiting_authorization. Ask the user to sign in or create a Voiceflow account in the browser and approve access. Wait for that process; do not start competing login flows. Do not save auth URLs or credentials in the repository. Wait for signed_in, then repeat the live workspace read. A closed browser, expired link, or cancelled login is not success. Offer one fresh login attempt if needed.

The callback runs on the CLI's machine. For SSH or containers, first establish supported loopback port forwarding using the current CLI instructions. If the user's browser cannot reach that listener, explain the limitation and offer local setup. Never claim a remote loopback URL has completed authentication.

Never ask for passwords, tokens, or secret values in chat. VF_TOKEN overrides stored OAuth credentials; inspect only its presence, not its value. Explain a stale override before changing it.

Return to guidance and completion.