Command line / tv

Up and running in 15 minutes.

Install tv, sign in, and put a real file through its whole lifecycle -- every step below is copy-paste, with the real output you'll see.

Start the walkthrough Read it as a doc page

Quick start: your first 15 minutes with `tv`

Thalix Vault has one interface today: a command-line program called tv. There is no upload button in a browser yet -- everything below happens in a terminal. This page walks a brand-new user through every day-one action, in order: install it, sign in, create a folder, put a real file through its whole lifecycle, share it, tidy it up, and keep tv current. Each step is one sentence of "why," the exact command to run, and the real output you'll see.

What you'll have by the end:

A verified copy of tv installed and on your PATH.
A signed-in session tied to your own Thalix Vault identity.
A Root Folder you can upload to.
One file you uploaded, found again two different ways, versioned, shared, archived, and restored -- proving nothing was ever lost along the way.
The one command that keeps tv itself current.

About this walkthrough: every command block below is real -- captured by actually running this build of tv against a live Thalix Vault stack, never invented. To make that possible and reproducible, it runs inside a small example organization with three identities already invited: demo-owner@files.test (that's "you" for the rest of this page, an ordinary member), demo-admin@files.test (the organization's administrator, who creates the first folder), and demo-other@files.test (a teammate we share a file with in Share it). Your own email, organization, and folder names will be different -- swap them in as you go. Every ID below (file, folder, grant, correlation) is a long UUID; to keep this page skimmable, each one is shown in full the first time and trimmed to its first 8 characters plus … after that (for example 0cc5e907-…). Always copy full values from your own terminal, never from this page.

M1 — Install `tv`

tv is the one thing you need before anything else -- every command on this page is something you type into it.

Download the signed macOS (Apple Silicon) build and make it executable:

curl -fsSL -o tv "https://github.com/thalixinc/thalix-vault-releases/releases/latest/download/tv-darwin-arm64"
chmod +x tv

Verify it's exactly what Thalix published, before you run it (recommended, one-time):

curl -fsSL -o SHA256SUMS "https://github.com/thalixinc/thalix-vault-releases/releases/latest/download/SHA256SUMS"
shasum -a 256 tv
grep tv-darwin-arm64 SHA256SUMS

You'll see the same 64-character string twice:

1ed98612cab636c27e3560cf297c1553e0b193c34ce1bda54d8fc9ed6b237133  tv
1ed98612cab636c27e3560cf297c1553e0b193c34ce1bda54d8fc9ed6b237133  tv-darwin-arm64

Put it on your PATH so plain tv works from any directory:

sudo mv tv /usr/local/bin/tv

Gatekeeper note (macOS): this binary is code-signed but not yet notarized by Apple. Downloading it with curl in Terminal, as above, does not trigger macOS's quarantine flag, so it should just run. If you instead downloaded it through a browser and macOS refuses to open it ("cannot be opened because the developer cannot be verified"), right-click the file in Finder and choose Open, or clear the flag yourself: xattr -d com.apple.quarantine tv.

Linux and Windows

Linux (x86_64):

curl -fsSL -o tv "https://github.com/thalixinc/thalix-vault-releases/releases/latest/download/tv-linux-x64"
chmod +x tv
sudo mv tv /usr/local/bin/tv

Windows (x86_64, PowerShell):

Invoke-WebRequest -Uri "https://github.com/thalixinc/thalix-vault-releases/releases/latest/download/tv-win32-x64.exe" -OutFile tv.exe

Windows builds are not code-signed at all yet, so SmartScreen shows an "unrecognized publisher" warning on first run; verify the checksum above, then choose "More info" → "Run anyway" if you trust the download. See Install tv for the full per-platform reference.

Confirm the install:

tv version --json

{
  "schemaVersion": 1,
  "command": "version",
  "cliVersion": "0.1.1",
  "backendVersion": null,
  "origin": { "source": "standalone", "binaryPath": "/usr/local/bin/tv", "rollbackAvailable": false }
}

origin.source: "standalone" confirms tv knows it's a signed release binary, not a developer's local build.

Checkpoint: you now have a verified copy of tv on your machine, on your PATH.

How you got here: your administrator sent an invitation

You're reading this because an administrator at your organization already sent you an invitation to join Thalix Vault. You received a clickable email link with a subject line like "Invitation to join Thalix Vault".

Following that link took you through these steps automatically:

A verification page confirmed your identity and established an authenticated session.
You became an active member of the organization with the role your administrator chose (usually user).
The page prompted you to set a password or reset a forgotten one.

From now on, sign-in works with your email and password — the invitation link is one-time-use and no longer needed. This page covers day-to-day sign-in with the password you just set.

Every command past this point needs to know who you are -- Thalix Vault has no anonymous access.

tv login

tv login prompts for your email, then your password:

Email: demo-owner@files.test
Password:

The password is read with echo disabled -- nothing appears as you type. Thalix Vault is invite-only: sign-in works only for an email your organization has already invited, and every password is at least 12 characters long. If you don't have a password yet -- for example right after accepting an invitation -- or you've forgotten it, open https://vault.thalixinc.ai/login and use Forgot password? to receive a reset link by email. Email links are used only for invitation acceptance and password resets: day-to-day sign-in never involves checking an inbox.

On success the terminal prints:

Authenticated with Thalix Vault.
Token: tv_C3Zddelx…
Expires: 2026-09-24T15:38:49.123Z
Scopes: account:read
Correlation ID: 3b617b19-…

Prefer signing in through the browser? tv login --browser falls back to the older one-time-code approval flow; see the Command reference for that mode's flags.

That … after the token is real -- tv never prints your full token, to the terminal or anywhere else. It's stored locally in a private, permissions-locked file; see Security and authorization if you want the detail.

Confirm who you're signed in as:

tv whoami

Authenticated as demo-owner@files.test (user)
Organization: 00000000-0000-4000-8000-000000000001
Status: active
Correlation ID: 9f131577-…

Your own email and organization ID will show instead. (user) is your role -- a regular member. An administrator's session shows (admin) or (global_admin) there instead; that distinction matters in the very next step.

Checkpoint: you have a signed-in session, and every command from here on uses it automatically.

M3 — Create or find your first Root Folder

Every file in Thalix Vault belongs to a Root Folder. You need the name of one before you can upload anything.

Any active member -- not only an administrator -- can create one. You become that Root Folder's owner and immediately have full manage access to it; nobody else can see or use it until you explicitly share it with tv folder access grant (see Access and delegation).

tv folder create "Client Onboarding"

Root Folder "Client Onboarding" created.
ID: 308c5c5c-2f88-4231-8795-fda38c5d6dc3
Owner: you@example.com
Status: active
Created: 2026-08-25T15:44:08+00:00
Correlation ID: 2fba75e3-…

A trimmed name only conflicts with another Root Folder you already own, active or previously deactivated (FOLDER_NAME_CONFLICT); a different owner may freely reuse the same name.

See what's now in your own default Root Folder:

tv folder list

Client Onboarding  folder  active  owner:you@example.com  (308c5c5c-2f88-4231-8795-fda38c5d6dc3)
1 item(s)
Correlation ID: 6a0f9d7f-…

(tv folder list [<folder-id>] browses only the immediate children of the selected folder -- your own default Root Folder when you omit the ID -- never a flattened subtree; re-run it with a child folder's ID to descend one level. It never includes anything you cannot already access, and a hidden or nonexistent folder ID both fail identically.)

Checkpoint: you own at least one Root Folder you can upload to. The rest of this page uses "Client Onboarding" -- swap in a Root Folder name of your own.

M4 — Upload, inspect, and download a file

This is the whole point: get a real file into the Vault, and get it back out again, byte-for-byte.

Create something to upload:

printf 'Welcome to the team!\n\nThis is your onboarding packet. Read chapters 1-3 before Friday.\n' > welcome.txt

Upload it:

tv file put welcome.txt --folder "Client Onboarding" --meta owner=onboarding-team --description "New-hire onboarding packet"

File "welcome.txt" uploaded as version 1.
File ID: 0cc5e907-fa6f-4a8a-8a97-ade2c699f944
Version: 1
Filename: welcome.txt
MIME type: text/plain
Size: 87 bytes
SHA-256: 84aacb76303217b0b6e57e187ddae9b70d270e07ce382bf59ac9a738383d5589
Correlation ID: f70ae432-…

--meta owner=onboarding-team fills in this organization's one required custom field, owner -- a plain text label an administrator defined with tv admin metadata create (it names who's accountable for the file's contents; it has nothing to do with your account). Run tv metadata list any time to see every field your own organization has defined and whether it's required. From here on this page refers to this file by its ID, shown trimmed as 0cc5e907-….

Look at what you uploaded:

tv file info 0cc5e907-fa6f-4a8a-8a97-ade2c699f944

File "welcome.txt" (0cc5e907-…)
Root Folder ID: 308c5c5c-…
Owner: c183a210-…
Status: active
Description: New-hire onboarding packet
Version: 1
Filename: welcome.txt
MIME type: text/plain
Size: 87 bytes
SHA-256: 84aacb76303217b0b6e57e187ddae9b70d270e07ce382bf59ac9a738383d5589
Metadata:
  owner: onboarding-team
Correlation ID: 61b5c661-…

(Owner here is your account's internal ID, not a display name -- this build doesn't print names yet, only the account you're signed in as and its ID.)

Get it back:

tv file get 0cc5e907-fa6f-4a8a-8a97-ade2c699f944 --output welcome-downloaded.txt

Downloaded "welcome.txt" version 1 to welcome-downloaded.txt
Version: 1
Filename: welcome.txt
MIME type: text/plain
Size: 87 bytes
SHA-256: 84aacb76303217b0b6e57e187ddae9b70d270e07ce382bf59ac9a738383d5589
Correlation ID: d264e569-…

Prove it's identical to what you uploaded:

shasum -a 256 welcome.txt welcome-downloaded.txt

84aacb76303217b0b6e57e187ddae9b70d270e07ce382bf59ac9a738383d5589  welcome.txt
84aacb76303217b0b6e57e187ddae9b70d270e07ce382bf59ac9a738383d5589  welcome-downloaded.txt

Same 64 characters, both lines. tv file get re-verifies this checksum itself, before it ever writes the file to disk -- a corrupted download fails outright and deletes the partial file, rather than silently handing you something wrong.

Checkpoint: you've round-tripped a real file through Thalix Vault, byte-for-byte.

M5 — Find it again

Real Root Folders hold hundreds of files. You need to find yours again without scrolling.

By name:

tv file find --folder "Client Onboarding" --name welcome

welcome.txt  0cc5e907-…  folder:308c5c5c-…  status:active  text/plain
1 file(s)
No more results.
Correlation ID: 99dd304f-…

By the metadata you set on it:

tv file find --meta owner=onboarding-team

welcome.txt  0cc5e907-…  folder:308c5c5c-…  status:active  text/plain
1 file(s)
No more results.
Correlation ID: 3f8f7bba-…

Through a whole folder subtree, instead of just its immediate contents:

tv file find --within 308c5c5c-… --name welcome

welcome.txt  0cc5e907-…  folder:308c5c5c-…  status:active  text/plain
1 file(s)
No more results.
Correlation ID: 7ad91c2e-…

--within matches the given folder plus everything nested beneath it, live from the current hierarchy every time you run it — a file moved into or out of that subtree changes the very next result. It composes with --name, --meta, and every other filter above, and the JSON form below echoes the requested folder back as withinFolderId so a script always knows which subtree a page came from.

As structured data, for a script or another program:

tv file find --folder "Client Onboarding" --json

{
  "schemaVersion": 1,
  "command": "file find",
  "files": [
    {
      "file": {
        "id": "0cc5e907-…",
        "name": "welcome.txt",
        "description": "New-hire onboarding packet",
        "folderId": "308c5c5c-…",
        "ownerUserId": "c183a210-…",
        "currentVersionNumber": 1,
        "status": "active",
        "createdAt": "2026-08-25T15:44:08+00:00",
        "updatedAt": "2026-08-25T15:44:08+00:00"
      },
      "mimeType": "text/plain",
      "metadataValues": { "owner": "onboarding-team" }
    }
  ],
  "nextCursor": null,
  "withinFolderId": null,
  "correlationId": "6cca4161-…"
}

--folder, --within, --name, --owner, --mime-type, date-range filters, and repeatable --meta all compose together -- see Working with files for the full filter set, and Automation and JSON output for scripting every command on this page with --json.

Checkpoint: you can find your file three different ways, and you know --json exists for when you need to script this.

M6 — Add a new version and see the history

Files change. tv keeps every version instead of overwriting one.

printf 'Welcome to the team!\n\nThis is your onboarding packet (v2). Read chapters 1-4 before Friday.\nAdded: benefits enrollment deadline is the 15th.\n' > welcome-v2.txt
tv file version add 0cc5e907-… welcome-v2.txt

File "welcome.txt" gained version 2.
File ID: 0cc5e907-…
Version: 2
Filename: welcome-v2.txt
MIME type: text/plain
Size: 141 bytes
SHA-256: e7ee80703ba6eac33cbf76e0e45ea9c12cf087905e500a3dabbf64675a287ac1
Correlation ID: 18f31b5a-…

See the full history, newest first:

tv file versions 0cc5e907-…

File "welcome.txt" (0cc5e907-…)
2  welcome-v2.txt  141 bytes  e7ee80703ba6eac33cbf76e0e45ea9c12cf087905e500a3dabbf64675a287ac1  2026-08-25T15:44:09+00:00
1  welcome.txt  87 bytes  84aacb76303217b0b6e57e187ddae9b70d270e07ce382bf59ac9a738383d5589  2026-08-25T15:44:08+00:00
2 version(s)
Correlation ID: a63aefee-…

tv file get now returns version 2 by default. Pull the original back with --version:

tv file get 0cc5e907-… --version 1 --output welcome-v1-again.txt

Downloaded "welcome.txt" version 1 to welcome-v1-again.txt
Version: 1
Filename: welcome.txt
MIME type: text/plain
Size: 87 bytes
SHA-256: 84aacb76303217b0b6e57e187ddae9b70d270e07ce382bf59ac9a738383d5589
Correlation ID: 04e70c69-…

Every historical version stays downloadable forever -- nothing is ever silently replaced.

Checkpoint: you have two versions of one file, and you can retrieve either one on demand.

A file locked to just you isn't useful. Grant a teammate exactly the access they need, nothing more.

tv file access grant 0cc5e907-… --user demo-other@files.test --level read --reason "Needs to review the onboarding packet"

Access granted: read  user:demo-other@files.test  (grant ed515b45-…)
Correlation ID: 8d8cb976-…

With read access, your teammate can look and download, but not change anything. From their own signed-in session:

tv file get 0cc5e907-… --output welcome-shared-copy.txt

succeeds --

Downloaded "welcome.txt" version 2 to welcome-shared-copy.txt
Version: 2
Filename: welcome-v2.txt
MIME type: text/plain
Size: 141 bytes
SHA-256: e7ee80703ba6eac33cbf76e0e45ea9c12cf087905e500a3dabbf64675a287ac1
Correlation ID: 7dda96f7-…

but changing it needs manage, which read doesn't grant:

tv file update 0cc5e907-… --set owner=someone-else --reason "test edit" --json

{
  "schemaVersion": 1,
  "error": {
    "code": "NOT_FOUND",
    "message": "No matching file was found.",
    "correlationId": "e9b07f8e-…"
  }
}

That's NOT_FOUND, not a "you're not allowed" message -- see Troubleshooting below for why that's deliberate.

Revoke access when they're done:

tv file access revoke 0cc5e907-… --user demo-other@files.test

Access revoked.
Correlation ID: 7c33d6db-…

After revoke, that same tv file get from your teammate's session goes back to the identical NOT_FOUND -- indistinguishable, from their side, from the file never having existed.

Checkpoint: you granted, used, and revoked access to one file, and watched the access boundary hold twice. See Access and delegation for grant levels, Root Folder-wide grants, and groups.

M8 — Tidy up: archive and restore

Retiring a file shouldn't mean losing its history.

tv file archive 0cc5e907-… --reason "Onboarding complete"

File "welcome.txt" archived.
File ID: 0cc5e907-…
Correlation ID: 614e6af8-…

It disappears from a default search:

tv file find --folder "Client Onboarding"

No files found.
0 file(s)
No more results.
Correlation ID: 5e8108a9-…

(add --archived to see archived files instead). Bring it back any time:

tv file restore 0cc5e907-… --reason "Needed again for the Q1 audit"

File "welcome.txt" restored.
File ID: 0cc5e907-…
Correlation ID: c4c65114-…

There is no delete command anywhere in tv. Archive and restore are reversible hiding, not deletion -- every version and every piece of history survives, permanently, by design. The database itself refuses to let anyone, including an administrator, delete a committed file or version row; see Trust boundaries for the enforcement detail.

Checkpoint: you archived and restored a file without losing anything.

M9 — Keep `tv` current

Signed releases keep shipping. Staying current is one command.

tv update

Most of the time, you'll see:

Already up to date.
Binary: /usr/local/bin/tv
Channel: stable
Platform: darwin-arm64

When a newer signed release really is available (this transcript is real too -- captured moving an installed 0.1.0 forward):

Updated 0.1.0 -> 0.1.1.
Binary: /usr/local/bin/tv
Channel: stable
Platform: darwin-arm64

tv update verifies the new release's signature, exact size, and checksum, and never accepts a downgrade, before it ever replaces the binary you're running.

One step back is always available immediately after an update, if you need it:

tv update --rollback

Rolled back 0.1.1 -> 0.1.0.
Binary: /usr/local/bin/tv
Channel: stable
Platform: darwin-arm64

Run it without a preceding update and it refuses instead -- there's nothing retained to roll back to yet:

{
  "schemaVersion": 1,
  "error": {
    "code": "RELEASE_NO_PREVIOUS_VERSION",
    "message": "tv update --rollback refused: no retained previous version is available. Rollback is available for one step immediately after a completed update.",
    "correlationId": "daae163e-…"
  }
}

Working from a private Git checkout instead of a downloaded binary? tv update still works the same way, but fast-forwards your checkout (git pull --ff-only) rather than replacing a binary -- see Install and update from a private Git checkout.

Checkpoint: you know the one command that keeps you current, and that one step back is always available right after you use it.

Troubleshooting

You see	Why	What to do
`AUTHENTICATION_REQUIRED` / "Run tv login before using tv whoami."	You're not signed in, or your session expired or was revoked.	Run `tv login` again.
macOS: "cannot be opened because the developer cannot be verified"	`tv`'s binaries are code-signed but not yet notarized by Apple. This only shows up if the download was quarantined -- typically a browser download, not `curl`.	Right-click the file in Finder → Open, or run `xattr -d com.apple.quarantine tv`.
`ACCOUNT_DEACTIVATED`	Your account, or your organization membership, was deactivated.	Contact your administrator -- this can't be self-resolved.
`NOT_FOUND` / "No matching file was found." on a file you're sure exists	`tv` never distinguishes "doesn't exist" from "exists, but you don't have enough access for this" -- both produce the identical error, deliberately, so a failed lookup never reveals what's really out there.	Ask whoever owns or manages the file to grant you access with `tv file access grant`.
`Error: Usage: tv ...` / "Run tv help for commands."	You mistyped a command, or left out a required flag.	Run `tv help`, or `tv help <command>`, for the exact flags -- or check the Command reference.
Any error, when you need help	Every `tv` error prints a Correlation ID -- a stable, safe reference for that one operation, even when nothing else about it is safe to share.	Save it and include it when you ask for help. An administrator can look up exactly what happened with `tv admin audit list --correlation <id>`; see Automation and JSON output.

What's next

Working with files -- every file command in depth: updating metadata, moving between Root Folders, and the validation errors you'll actually hit.
Access and delegation -- grant levels, Root Folder-wide grants, and groups, in depth.
Automation and JSON output -- the stable --json envelope, exit codes, and the full error-code table, for scripting every command on this page.
Command reference -- the authoritative syntax, permission, and error source for every tv command, including the ones this page didn't cover (tv admin metadata, tv admin user, tv admin group, tv admin audit list, tv skill install).