triosurf-cli

TrioSurf CLI — authenticate and sync marketing plans from your terminal.

Install

No install needed. Use npx:

npx triosurf-cli auth

Or install globally:

npm install -g triosurf-cli
triosurf auth

Commands

triosurf auth

Authenticate this device via browser. Opens a browser window for you to approve the device, then saves credentials to ~/.config/triosurf/config.json (permissions 0600).

$ triosurf auth

⠸ Requesting device code...
✓ Device code requested

   Your code:  ABCD-EFGH

   Open in browser:
   https://mktcal.vercel.app/device?code=ABCD-EFGH

   Browser opened automatically.

⠸ Waiting for authorization...
✓ Authorized as [email protected]

✓ Saved to ~/.config/triosurf/config.json
✓ You can now use TrioSurf from any terminal on this machine.

Options:

• --force — Overwrite existing credentials
• --api-url <url> — Custom TrioSurf server URL (default: https://mktcal.vercel.app)

triosurf status

Show current authentication status.

$ triosurf status

✓ Authenticated

  User:    [email protected]
  Key:     mk_a1b2c3d4...
  Since:   4/15/2026, 2:30:00 PM
  Server:  https://mktcal.vercel.app
  Config:  /Users/you/.config/triosurf/config.json

triosurf logout

Remove saved credentials.

$ triosurf logout

✓ Credentials removed from /Users/you/.config/triosurf/config.json

triosurf link

Bind the current directory to a TrioSurf cloud project. After this, every Claude Code session you run in this directory (or any subdirectory) is automatically synced to your dashboard — no per-session setup, no tags to remember.

$ cd ~/code/my-saas
$ triosurf link

Link /Users/you/code/my-saas to a TrioSurf project:

   1. My SaaS Marketing  ← cwd match
   2. Side Project
   3. + Create new project "my-saas"
   c. Cancel

Choice [1]: <enter>

✓ Linked to My SaaS Marketing
  Saved to /Users/you/code/my-saas/.triosurf/project.json
  This file should be committed so collaborators share the project.

The CLI smart-matches the cwd basename against your existing cloud projects. Pressing enter accepts the suggestion. To create a new cloud project on the fly, pick the last option.

.triosurf/project.json is intended to be committed to git so all collaborators on the repo share the same dashboard. Each user authenticates separately with their own triosurf auth.

triosurf hooks install|uninstall|status

Wires Claude Code's lifecycle hooks (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop) into TrioSurf. After install, every Claude Code session in a linked directory auto-creates a session record on your dashboard with all tool calls timestamped, and a Claude-generated summary as the title.

$ triosurf hooks install
✓ TrioSurf hooks installed into ~/.claude/settings.json
  Backup saved to settings.json.triosurf.bak
  Restart Claude Code sessions to pick up the new hooks.

triosurf auth offers to do this automatically — you usually don't need to run it manually.

| Event | What lands on the dashboard | |--------------------|--------------------------------------------------------------| | SessionStart | New kind=session action created in the linked project | | PreToolUse | Progress event with toolName and phase=pre | | PostToolUse | Progress event with toolName, phase=post, error flag | | UserPromptSubmit | note_added event (length only, never the prompt text) | | Stop | Session marked completed; transcript summarized → title |

In unlinked directories the hook silently no-ops, so you can use Claude Code anywhere without polluting the dashboard. The first time a new directory is detected, a single stderr line nudges you with run: triosurf-cli link; thereafter that directory is permanently silent.

When offline, events are appended to ~/.local/state/triosurf/event-queue.jsonl and flushed on the next successful hook run.

$ triosurf hooks status
TrioSurf hooks status
  /Users/you/.claude/settings.json

  ✓ SessionStart
  ✓ PreToolUse
  ✓ PostToolUse
  ✓ Stop
  ✓ UserPromptSubmit

$ triosurf hooks uninstall
✓ Removed 5 TrioSurf hook entries.

Config location

Credentials are stored in ~/.config/triosurf/config.json (or $XDG_CONFIG_HOME/triosurf/config.json).

File permissions: 0600 (owner read/write only).

How it works

This CLI implements OAuth 2.0 Device Authorization Grant (RFC 8628) — the same flow used by gh auth login and other modern CLIs.

1. CLI requests a device code from the server
2. User visits a URL in their browser and approves the device
3. CLI polls the server until the user approves
4. Server issues an API key to the CLI
5. CLI saves the key locally

No copy-paste, no env var configuration.

License

MIT