Getting started with `tv`

tv is the only supported interface for Thalix Vault file and administrative operations. This page gets a new user from zero to a first uploaded file.

First time here? Quick start covers the same ground as a 15-minute, copy-paste walkthrough with real command output for every step -- this page is the terser, reference-style version.

Implementation status: browser device tv login, scoped tv whoami/tv logout, tv file put|find|get, and tv update are implemented and covered by real-executable tests. A private-Git checkout can install and use all of this today (below). The standalone signed installer's engine, signing, and update tooling are also implemented (#12), but no release has actually been published yet — the thalixinc/thalix-vault-releases repository, download links, and production login endpoint do not exist yet. Do not treat the standalone download commands below as available until Install tv drops its own blocked notice.

1. Install

Pick the path that matches your access:

You have a private thalix-vault Git checkout (developers, early operators): follow Install and update from a private Git checkout. In short:

bun run build:node && bun link --cwd packages/cli
tv version --json

You only have a released binary (once a release is published): follow Install tv (standalone binary) for the platform-specific download, checksum verification, and tv update staying-current instructions.

Verify either install with:

tv version --json

A git-checkout install reports origin.source: "git-checkout" with the checkout's commit, branch, and path; a standalone install reports origin.source: "standalone". Verified output from this worktree:

{
  "schemaVersion": 1,
  "command": "version",
  "cliVersion": "0.1.0-dev",
  "backendVersion": null,
  "origin": {
    "source": "git-checkout",
    "commit": "5736e0758bec0456e7e1f508d7ec38918cf55d5a",
    "describe": "5736e07",
    "branch": "feat/mvp-013-documentation",
    "checkoutPath": "/private/tmp/tv-013"
  }
}

backendVersion is null because tv version never calls the backend; it only reports the local CLI build and its own install origin.

tv login

tv login prompts for your email, then reads your password with echo disabled — sign-in is email-and-password, and it works only for an email your organization has already invited (every password is at least 12 characters long). If you don't have a password yet or have forgotten it, use Forgot password? on the web sign-in page (/login) to receive a reset link by email; email links are used only for invitation acceptance and password resets. After authentication the CLI stores an opaque, revocable token — never your password, and never a Supabase access or refresh token. tv login --browser falls back to the older device-approval flow (a one-time code plus a browser approval page) if you cannot use a terminal password prompt.

tv whoami

reports your account, organization, and role once signed in. If you are not signed in, every protected command fails the same way (captured from this build with no session file present):

{
  "schemaVersion": 1,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Run tv login before using tv whoami.",
    "correlationId": "9ec9dec8-90a9-4741-946a-bdd7f6ade22f"
  }
}

Development requires a running local application server and an explicit origin (--base-url http://localhost:4174 or THALIX_BASE_URL=http://localhost:4174); the CLI never guesses a backend to talk to. See CLI overview for the full login contract and Security and authorization for where the token lives on disk.

When you are done for the session, tv logout revokes the token and clears it locally.

3. Discover where things go

tv folder list
tv metadata list

tv folder list [<folder-id>] browses only the immediate children (folders and files) of the selected folder -- your own default Root Folder ("My Files") when you omit the ID -- never a flattened subtree; re-run it with a child folder's ID to go one level deeper. tv metadata list lists every currently-active custom metadata field your organization has defined, so you can populate --folder and --meta correctly without guessing. Both require only an authenticated session -- any organization member may run them, not just an administrator.

4. Put, find, and get a file

tv file put ./example.pdf --folder "Example Root Folder" --meta reviewed=false
tv file find --folder "Example Root Folder"
tv file info <file-id>
tv file get <file-id> --output ./example.pdf

tv file put streams the file straight to private object storage through a short-lived, server-minted signed URL — the CLI never sees an object-storage credential — computing its SHA-256 and byte count as bytes pass through. tv file find searches your own accessible files with typed metadata filters; tv file get re-verifies the downloaded bytes' size and checksum against what the backend declares and removes any partial file on mismatch. Missing --folder fails fast with a usage error before any network call, for example (captured from this build):

{
  "schemaVersion": 1,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Usage: tv file put <path> --folder <folder> [--meta key=value ...] [--description <text>] [--mime-type <type>] [--json]",
    "correlationId": "9810e1a3-c5d2-44e1-9019-ea4a7217da4c"
  }
}

Continue with Working with files for versions, updates, moves, and archive/restore, and Access and delegation for sharing a file or Root Folder with someone else. The Command reference is the authoritative syntax, permission, and error-code source for every command mentioned on this page.

Getting started with tv

1. Install

2. Sign in

3. Discover where things go

4. Put, find, and get a file

Getting started with `tv`