Thalix VaultDocumentation
Browse documentation
CLI Reference
draftpartially implementedEdit this page

CLI overview

The executable is named tv. It is the only supported interface for file and administrative operations in the MVP.

Implementation status: partially implemented. A private local-development package provides tested tv version (including Git checkout origin reporting), tv dev capabilities, email-and-password tv login with a --browser device-approval fallback (#22), scoped tv whoami and tv logout (#23), a private-Git tv update (#25), tv folder create (any active member, not just an administrator), tv folder list (one-level browse of a folder's immediate children, issue #56) plus tv metadata list discovery, tv admin folder list|deactivate, and the full tv admin metadata create|list|show|update|deactivate group (#5), tv file put|info|get (#6), tv file find|update|move plus tv file info --revisions and folder-subtree-scoped search via --within <folder-id> (#7, issue #57), tv file version add|versions, tv file get --version, tv file archive|restore, and tv file find --archived (#8), tv admin user list|deactivate|role, tv admin group create|list|add-member|remove-member, tv file access grant|revoke|list, and tv folder access grant|revoke|list (#9), and tv admin audit list plus the tv file info|get --admin-reason <reason> exceptional-administrator-access override (#10). Card #24 and tv admin user invite remain planned. No public npm release, signed installer (see #12), or Tauri client is implemented.

Command families

  • tv version reports the local development CLI version in human or JSON form.
  • tv dev capabilities calls an explicitly enabled, non-sensitive development endpoint and reports a validated correlation ID.
  • tv login signs in with an invited email and password (--password-stdin for automation; a password is never accepted on the command line) and atomically writes the issued opaque token to a private XDG/AppData credential file; --browser falls back to the older device-approval flow.
  • tv file put|info|get uploads, inspects, and downloads files; tv file find supports typed metadata (--meta), free-form tag (--tag) and live subtree (--within) filters with keyset pagination; tv file update changes typed metadata with immutable revision history; and tv file move relocates files with atomic access recalculation. Version and archive/restore commands preserve immutable content history. Administrators may inspect and download organization content without a grant; --admin-reason is optional, and every override is recorded as admin.content.access.
  • tv folder create lets any active member -- not only an administrator -- create and own a Root Folder, with implicit manage and no separate grant row for that ownership; tv folder list [<folder-id>] (issue #56) browses only a folder's immediate child folders/files one level at a time -- never a recursively flattened subtree -- defaulting to the caller's own default Root Folder when the ID is omitted, keyset-paginated (--limit/--cursor) with archived entries opt-in (--include-archived) and no bytes/URLs/tags/metadata/grants/audit history on any row; tv metadata list discovers every active custom metadata definition; tv admin folder list|deactivate (every Root Folder regardless of owner or status) and tv admin metadata create|list|show|update|deactivate remain administrator-gated.
  • tv admin user list|deactivate|role manages organization members and roles. Active members create user-owned groups with tv group create; owners and managers use invitations and role commands, while explicit tv admin group list|members|remove-member|transfer commands provide audited administrator recovery without implicit membership. tv file access grant|revoke|list and tv folder access grant|revoke|list delegate additive read/write/manage access to users or groups; folder grants inherit through descendants, delegation is bounded by the caller's live authority and subtree, and there is no deny ACL. tv admin audit list retrieves the unified, filtered, keyset-paginated audit view.
  • tv skill install|doctor|update|uninstall|export installs, verifies, updates, and removes the bundled thalix-vault Agent Skill for Claude Code/Codex, and exports ChatGPT browser guidance (#11); see Agent Skill.
  • tv update [--rollback] fast-forwards a private-Git checkout install (git pull --ff-only), or verifies and atomically activates a signed release for a standalone install, detecting which applies automatically; --rollback restores a standalone install's one retained previous version. See Install and update from a private Git checkout and Install/Releasing tv (#12).

Behavioral contract

  • Human-readable output is the default; --json is available for automation.
  • Bare tv, tv help, and tv --help print a grouped command listing to standard output and exit 0; tv help <command> (or tv <command> --help) prints that command's full flag syntax. A usage error (unrecognized command, missing/invalid flag) prints only that command's one-line usage plus Run tv help for commands., never the full command list. See Command reference.
  • Failures return non-zero exit codes.
  • JSON errors contain a stable error code, message, and correlation ID.
  • Secrets, passwords, refresh credentials, and storage credentials are never printed.
  • Access-reducing or destructive administrative actions request confirmation unless --yes is supplied.
  • Uploads and downloads stream bytes and checksums rather than loading an entire file into memory.
  • The supported initial file-size target is up to 1 GiB, subject to infrastructure verification.
  • The implemented tv version reports the CLI development version, the backend as not connected, and — when running from a linked Git checkout — the checkout's commit, optional tag description, branch, and path. Full compatibility negotiation remains planned.

Production login defaults to https://vault.thalixinc.ai. The fallback device-approval flow's activation URLs begin https://vault.thalixinc.ai/cli/activate?code=. Development requires a running local application server and an explicit --base-url or THALIX_BASE_URL override. The browser create, poll, and decision handshake uses internal routes and is not a public API.

Implemented login behavior

Sign-in is email-and-password by default; wrong credentials and passwordless accounts return one uniform INVALID_CREDENTIALS error, and repeated attempts are rate-limited per email and globally. Successful login stores the issued opaque device token and safe metadata without printing the token. No CLI path parses, stores, refreshes, or transmits Supabase access or refresh credentials. tv whoami sends the opaque token only as a bearer to the internal Vault route and returns a verified safe account projection. tv logout clears locally after confirmed revocation or confirmed prior invalidation; uncertain or hostile responses preserve the credential for a safe retry.

Every CLI failure exposes a safe correlation ID. Network failures retain the validated request correlation, local authorization expiry keeps the last request correlation, persistence failure after issuance keeps the token-response correlation, and a pre-network failure uses a generated local correlation.

Credential-file paths, exact schema, permissions, atomic replacement, and path defenses are authoritative in Security and authorization and ADR-0005. Abuse accounting, audit, service-boundary evidence, secret exclusions, and cross-boundary correlation are authoritative in Audit and observability.

New here? Start with the Quick start for a 15-minute, copy-paste walkthrough with real command output. Continue with Getting started, Command reference, Automation output, Install and update from a private Git checkout, Install the standalone binary, or Releasing tv.