CLI

The Tusky CLI (@tuskydp/cli) provides command-line access to all Tusky operations — file management, vault operations, encryption, and the MCP server for AI agents.

Installation

npm install -g @tuskydp/cli

Verify the installation:

tusky --version

Global options

These flags apply to every command:

Flag	Description	Default
`--api-key <key>`	Override API key	stored config / `TUSKYDP_API_KEY` env
`--api-url <url>`	Override API URL	`https://api.tusky.ai`
`--format <fmt>`	Output format: `table`, `json`, `plain`	`table`
`--quiet`	Suppress non-essential output	`false`
`--verbose`	Show debug output	`false`
`--no-color`	Disable colored output	—

Configuration is stored in ~/.config/tuskydp/config.json.

Authentication

`tusky signup <email> <password>`

Create a new account. Automatically creates and stores a CLI API key.

Flag	Description
`--name <name>`	Display name for the account

`tusky login`

Authenticate with Tusky. Three modes:

# With an existing API key
tusky login --api-key tdp_your_key

# With email and password (auto-creates an API key)
tusky login --email [email protected] --password your_password

Flag	Description
`--api-key <key>`	Authenticate with an existing API key
`--email <email>`	Email address
`--password <password>`	Password

`tusky logout`

Clear stored credentials and encryption session.

`tusky whoami`

Show current user, plan, and storage usage.

API keys

`tusky api-keys list`

List all API keys in a table with name, prefix, scopes, last used, and created date.

`tusky api-keys create <name>`

Create a new API key. The full key is shown once — save it.

Flag	Description
`--scopes <scopes>`	Comma-separated scopes
`--vaults <vaults>`	Comma-separated vault IDs to restrict access
`--expires <days>`	Auto-expire after N days

`tusky api-keys revoke <key-id>`

Revoke an API key by ID.

Vaults

`tusky vault create <name>`

Create a new vault. Private (encrypted) by default.

Flag	Description
`--public`	Create as a public vault (unencrypted, shareable)
`--description <text>`	Vault description

tusky vault create "My Project"
tusky vault create "Shared Data" --public

`tusky vault list`

List all vaults with name, slug, visibility, file count, size, and ID.

`tusky vault info <vault>`

Show vault details. Accepts a vault ID, slug, or name.

`tusky vault rename <vault> <new-name>`

Rename a vault. Accepts a vault ID, slug, or name.

`tusky vault delete <vault>`

Delete a vault. Prompts for confirmation unless --force is passed.

Flag	Description
`--force`	Delete the vault and all its files without confirmation

`tusky vault set-default <vault>`

Set the default vault for uploads. When set, tusky upload uses this vault unless --vault is specified.

Files

`tusky ls [vault]`

List files. Optionally filter by vault (ID, slug, or name).

Flag	Description	Default
`--sort <field>`	Sort by `name`, `size`, or `date`	`date`
`--status <status>`	Filter by status: `hot`, `synced`, `cold`, `error`	—
`--limit <n>`	Max results	`50`
`-f, --follow`	Watch mode — refresh every 3 seconds	—

tusky ls                        # All files
tusky ls my-vault --status hot  # Hot files in a specific vault
tusky ls -f                     # Watch mode

`tusky info <file-id>`

Show file details — name, size, MIME type, status, Walrus blob ID, upload date.

`tusky status <file-id>`

Show sync status and Walrus blob ID for a file.

`tusky retry [file-ids...]`

Retry failed Walrus sync. If no IDs are given, retries all files in error status.

tusky retry                           # Retry all errored files
tusky retry abc123 def456             # Retry specific files

`tusky rm <file-ids...>`

Soft-delete one or more files (moves to trash). Prompts for confirmation unless --force is passed.

Flag	Description
`--force`	Skip confirmation prompt

Upload and download

`tusky upload <paths...>`

Upload files to a vault. For private vaults, encryption is handled automatically.

Flag	Description
`--vault <vault>`	Target vault (ID, slug, or name). Falls back to the default vault.
`--recursive`	Upload directory contents recursively

tusky upload photo.jpg --vault my-vault
tusky upload ./docs --vault my-vault --recursive
tusky upload file1.txt file2.txt

`tusky download <file-id>`

Download a file. For private vaults, decryption is handled automatically. Cold files are rehydrated from Walrus on demand (polls up to 60 seconds).

Flag	Description
`--output <path>`	Output path (defaults to current directory + original filename)

tusky download abc123
tusky download abc123 --output ./downloads/myfile.pdf

Encryption

Encryption is required for private vaults. See the encryption guide for details on the key hierarchy and security model.

`tusky encryption setup`

Set your encryption passphrase for the first time. Generates a master key, wraps it with your passphrase, and displays a recovery key. Save the recovery key — it’s shown once.

`tusky encryption unlock`

Unlock encryption for the current session. Stores the master key in ~/.tusky/session.enc.

Flag	Description
`--passphrase <passphrase>`	Passphrase (also reads `TUSKYDP_PASSWORD` env var). Prompts interactively if omitted.

tusky encryption unlock
tusky encryption unlock --passphrase "my passphrase"
TUSKYDP_PASSWORD="my passphrase" tusky encryption unlock

`tusky encryption status`

Show whether encryption is set up (server-side) and whether the session is unlocked (local).

`tusky encryption change-passphrase`

Change your encryption passphrase. Re-wraps the master key — existing encrypted files remain accessible. Generates a new recovery key.

`tusky encryption recover`

Recover your master key using the recovery key. Sets a new passphrase and generates a new recovery key.

Account

`tusky account info`

Show account info — email, plan, storage usage, encryption status. Also runs when you type tusky account with no subcommand.

`tusky account plan`

Show your current plan and available upgrades with pricing, storage limits, and max file sizes.

`tusky account usage`

Show detailed storage usage breakdown per vault — name, visibility, file count, and size.

MCP server

The MCP server lets AI agents call Tusky operations as tools. See the full MCP Server guide for setup and tool reference.

`tusky mcp serve`

Start the MCP server using stdio transport (JSON-RPC over stdin/stdout). Designed to be launched by an AI agent, not run manually.

`tusky mcp install-config`

Write the MCP server configuration to your agent’s config file.

Flag	Description	Default
`--target <target>`	Agent target: `claude-code`, `claude-desktop`, `cursor`	`claude-code`
`--api-key <key>`	API key to embed in the config	stored key
`--api-url <url>`	API URL override	—

Disaster recovery

Tusky is designed so you can recover your data independently — without the Tusky API or platform. See the file lifecycle guide for context on how files move between storage tiers.

`tusky export`

Export file metadata for disaster recovery. Produces a JSON manifest containing Walrus blob IDs, encryption metadata, and step-by-step recovery instructions.

Flag	Description	Default
`-o, --output <path>`	Output file path	`tusky-export.json`
`--vault <vaultId>`	Export only a specific vault	all vaults

tusky export
tusky export -o backup.json --vault abc123

The export manifest includes:

Every file’s Walrus blob ID and Sui object ID
Encryption metadata (wrapped keys, IVs, checksums)
Walrus network info and aggregator URL
Recovery instructions for fetching and decrypting files without Tusky

`tusky decrypt <encrypted-file>`

Decrypt a file that was downloaded from Walrus using your encryption passphrase. Three modes for resolving encryption metadata:

Flag	Description
`-o, --output <path>`	Output path for the decrypted file
`--export <path>`	Path to a `tusky-export.json` manifest (offline mode)
`--file-id <id>`	Tusky file ID (online — fetches metadata from API)
`--wrapped-key <key>`	Per-file wrapped key, base64 (manual mode)
`--iv <iv>`	Per-file encryption IV, base64 (manual mode)
`--checksum <sha256>`	Expected plaintext SHA-256 checksum, hex
`--passphrase <passphrase>`	Encryption passphrase (also reads `TUSKYDP_PASSWORD` env)

# Offline with export manifest
tusky decrypt myfile.enc --export tusky-export.json -o myfile.txt

# Online, fetches metadata from API
tusky decrypt myfile.enc --file-id abc123 -o myfile.txt

# Manual keys
tusky decrypt myfile.enc --wrapped-key <b64> --iv <b64> -o myfile.txt

`tusky rehydrate <blob-id>`

Download a file directly from the Walrus network by blob ID. Does not decrypt — the downloaded file will be encrypted if it came from a private vault.

Flag	Description
`--output <path>`	Output file path (defaults to `blob-<blobId>` in current directory)

tusky rehydrate Bx7K9...abc --output myfile.enc

Interactive TUI

`tusky tui`

Launch a full-screen interactive terminal UI for browsing vaults, managing files, and authentication.

MCP Server Full guide to setting up the MCP server for AI agents.

Encryption How the key hierarchy and client-side encryption works.