ViviScape.CLI 0.6.0

ViviScape CLI (vs)

Command-line interface for WorkOS by ViviScape.

Install

Requires the .NET 8 SDK (or newer).

dotnet tool install -g ViviScape.CLI

Open a new terminal and:

vs auth login    # browser opens → click "Allow access"
vs --help

Upgrade:

dotnet tool update -g ViviScape.CLI

Uninstall:

dotnet tool uninstall -g ViviScape.CLI

If vs isn't found, ensure %USERPROFILE%\.dotnet\tools is on PATH (the .NET SDK installer normally adds it; just open a fresh terminal).

Build from source

git clone https://viviscapesoft.visualstudio.com/ClockWyzWeb/_git/ClockWyzWeb
cd ClockWyzWeb\ViviScape.CLI
.\install.ps1                  # pack + install locally
.\install.ps1 -Reinstall       # force a clean reinstall

Publish a new release (maintainer)

# bump <Version> in ViviScape.CLI.csproj first
dotnet pack .\ViviScape.CLI\ViviScape.CLI.csproj -c Release
dotnet nuget push .\ViviScape.CLI\nupkg\ViviScape.CLI.<version>.nupkg `
    -s https://api.nuget.org/v3/index.json `
    -k <NUGET_API_KEY>

Auth

The CLI uses a browser-based loopback flow (similar to gh auth login):

1. vs auth login starts a local listener on http://127.0.0.1:<random> and opens https://work.viviscape.io/auth/cli/connect?port=<port>&state=<csrf> in your browser.
2. The bridge page (rendered by AuthController.CliConnect) reads your existing WorkOS session (access_token, aid, auth) from sessionStorage and POSTs it to the CLI's localhost callback. If you aren't signed in, it sends you to /login#cli=<bridge-url> and login.js returns you to the bridge after auth.
3. The CLI verifies the state token and stores the credentials in:
   • Windows → Windows Credential Manager (ViviScape.CLI:default)
   • macOS / Linux → ~/.viviscape/credentials.json (chmod 600)

API requests use the standard WorkOS headers user_id, pid, plus a Bearer access token.

Override the API host with VIVISCAPE_BASE_URL (defaults to https://work.viviscape.io).

Commands

vs auth login | logout | status

vs projects ls [--company <id>] [--json]
vs companies ls [--json]

vs tasks ls [--json]
vs tasks get <task_id>
vs tasks add --title "..." --group <group_id> [--description ...] [--due <iso>]
             [--priority low|normal|high] [--service <id>] [--estimate 4h]
vs tasks update <task_id> --set status=onhold --set priority=high
vs tasks done <task_id>
vs tasks log <task_id> --note "..." [--hours 1.5] [--minutes 30] [--when <iso>] [--billable]

vs tickets ls [--status open|closed|all] [--query ...] [--json]
vs tickets get <ticket_id>

vs time in  [--note "..."]
vs time out [--note "..."]
vs time history [--json]

vs logs ls [--json]
vs logs add --note "..." [--hours 1.5] [--minutes 30] [--service <id>] [--when <iso>]
vs logs rm <log_id>
vs logs hours [--start <date>] [--end <date>] [--json]
vs logs hours-by-service [--start <date>] [--end <date>] [--json]
vs logs alltime [--json]

vs notes ls [--json]
vs notes get <note_id>
vs notes add [--title "..."] (--note "..." | --file path) [--public] [--summary]
             [--book <id>] [--knowledge]
vs notes edit <note_id> [--title ...] [--note ... | --file path] [--public]
vs notes rm <note_id>

vs comment ls <task_id> [--json]
vs comment add <task_id> "comment text"
vs comment edit <comment_id> "new text"      # known issue: upstream returns 400
vs comment rm <comment_id>

Plans

Commands are gated by your plan_type to mirror the portal sidebar:

A blocked command prints a clean message with an upgrade link and exits 1. Set VS_FORCE_PLAN=starter|pro|premium|enterprise to test the gate locally without changing your account.