CLI Commands

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

Installation

npm install -g @opentusk/cli

Verify the installation:

opentusk --version

Global options

These flags apply to every command:

Flag	Description	Default
--api-key <key>	Override API key	stored config / OPENTUSK_API_KEY env
--api-url <url>	Override API URL	https://api.opentusk.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/opentusk/config.json.

Setup

opentusk setup

Interactive onboarding wizard. Walks you through account creation, login, and agent setup in one guided flow.

Three paths:

1. Create a new account — email, password, access code, display name, API key generation, optional Sui wallet setup, optional vault creation.
2. Log in — email/password or API key, then optional Sui wallet and vault configuration.
3. Set up an agent — paste an invite code, generate (or reuse) a Sui keypair, redeem for an API key.

If you’re already logged in, setup detects your session and offers to show your current configuration, fill in missing setup (Sui wallet, default vault), or log in as a different user.

opentusk setup                     # Interactive wizard
opentusk setup --api-url <url>     # Override API URL

---

Authentication

opentusk signup <email> <password>

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

Flag	Description
--access-code <code>	(required) Access code for signup
--name <name>	Display name for the account

opentusk login

Authenticate with OpenTusk. Four modes:

# With an invite code (recommended for agents)
opentusk login --invite-code otinv_abc123...

# With an existing API key
opentusk login --api-key otk_your_key

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

Flag	Description
--invite-code <code>	Authenticate via invite code (for agents) — generates Sui keypair, creates API key
--api-key <key>	Authenticate with an existing API key
--email <email>	Email address
--password <password>	Password

When using --invite-code, the CLI generates a Sui keypair (or uses an existing one), redeems the code for an API key, and stores everything in config. The Sui key is locked — setup-sui and clear-sui are blocked until logout.

opentusk logout

Clear stored credentials.

opentusk whoami

Show current user, plan, and storage usage.

---

Setting up encryption

OpenTusk uses SEAL encryption for shared vaults. Public vaults are unencrypted.

Vault type	Encryption	Identity	Setup required
Shared	SEAL protocol (IBE)	Your Sui private key	opentusk account setup-sui or OPENTUSK_SUI_PRIVATE_KEY env
Public	None	N/A	None

Shared vault encryption (SEAL)

Shared vaults use the SEAL protocol — an on-chain identity-based encryption scheme where access is controlled by Sui addresses. Your Sui private key is the credential.

Setup (interactive):

The opentusk setup wizard handles this automatically — it generates a Sui keypair and links it to your account. You can also set it up manually:

# Store a Sui private key in CLI config
opentusk account setup-sui suiprivkey1...

# Link the address to your account (one-time)
opentusk account link-sui <your-sui-address>

Once set, all uploads to and downloads from shared vaults are encrypted and decrypted automatically.

Automation and non-interactive use:

For scripts, CI, or agent environments, set both variables and skip interactive prompts entirely:

export OPENTUSK_API_KEY=otk_your_key
export OPENTUSK_SUI_PRIVATE_KEY=suiprivkey1...

# Uploads to shared vaults are SEAL-encrypted automatically
opentusk upload secrets.pdf --vault "Team Vault"

# Downloads are decrypted automatically
opentusk download <file-id> --output secrets.pdf

The OPENTUSK_SUI_PRIVATE_KEY env var takes precedence over the stored config key.

---

Account

opentusk account info

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

opentusk account plan

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

opentusk account usage

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

opentusk account link-sui <sui-address>

Link a Sui wallet address to your account. Required before creating or joining shared vaults.

opentusk account link-sui 0x1234...abcd

opentusk account unlink-sui

Remove the linked Sui wallet address from your account.

opentusk account setup-sui [<private-key>]

Save a Sui Ed25519 private key to config for shared vault operations.

opentusk account setup-sui suiprivkey1...

opentusk account show-sui

Show the configured Sui address (does not reveal the private key).

opentusk account clear-sui

Remove the stored Sui private key from config.

opentusk account api-keys list

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

opentusk account 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

opentusk account api-keys revoke <key-id>

Revoke an API key by ID.

opentusk invite create

Create a single-use invite code for agent onboarding.

Flag	Description
--name <name>	Label for the API key created on redemption
--scopes <scopes>	Comma-separated scopes for the API key
--vaults <vaults>	Comma-separated vault IDs the key can access
--expires <hours>	Expiry in hours (default: 1)

opentusk invite create --name "cursor-agent" --expires 24

opentusk invite list

List all invite codes with their status (pending, redeemed, expired).

opentusk invite revoke <invite-code-id>

Revoke an unredeemed invite code.

---

Vaults

opentusk vault create <name>

Create a new vault. Shared (SEAL-encrypted) by default. Use --public to create an unencrypted public vault.

Flag	Description
--public	Create as a public vault (unencrypted, no Sui key required)
--description <text>	Vault description

opentusk vault create "Team Vault"               # shared (default)
opentusk vault create "Public Assets" --public   # public, unencrypted

opentusk vault list

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

opentusk vault info <vault>

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

opentusk vault rename <vault> <new-name>

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

opentusk vault update <vault>

Update vault name and/or description.

Flag	Description
--name <name>	New vault name
--description <text>	New vault description

opentusk vault delete <vault>

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

Flag	Description
--yes	Skip confirmation prompt

opentusk vault set-default <vault>

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

opentusk vault shared

List shared vaults you’ve been granted access to (not vaults you own). Shows name, slug, role, file count, size, and granted date.

opentusk vault members list <vault>

List all members of a shared vault. Shows Sui address, role, granted date, and member ID.

opentusk vault members add <vault> <sui-address>

Grant access to a shared vault by the new member’s Sui address.

opentusk vault members remove <vault> <member-id>

Revoke access from a shared vault member by their member ID. Prompts for confirmation unless --yes is passed.

Flag	Description
--yes	Skip confirmation prompt

---

Files

opentusk ls [vault]

List files. Shortcut for opentusk file list. Optionally filter by vault (ID, slug, or name).

Flag	Description	Default
--sort <field>	Sort by name, size, or date	date
--limit <n>	Max results	50
--folder <folder-id>	Filter by folder ID	—
-f, --follow	Watch mode — refresh every 3 seconds	—

opentusk ls                    # All files
opentusk ls my-vault           # Files in a specific vault
opentusk ls -f                 # Watch mode

opentusk file list [vault]

List files in a vault. Same options as opentusk ls.

opentusk file info <file-id>

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

opentusk file info <file-id>
opentusk file info <file-id> --format json | jq .data.status

opentusk file status <file-id>

Show sync status, Walrus blob ID, and storage lifetime for a file. For PPU files, also shows the payment mode, total epochs paid (initial purchase + extensions), the expiry date, the number of epochs remaining, and the auto-renew setting. For subscription files with a Walrus lease, shows the current lease expiry.

Flag	Description
--wait	Poll until status is synced or error (max 5 minutes)

opentusk file status <file-id>
opentusk file status <file-id> --wait   # blocks until synced

Example output for a PPU file:

File:        report.pdf
Status:      synced
Walrus Blob: AoHT9eo4JpOvA6xW-ndMcpCg8GNhMtb0xKuJw0kv2hI
Payment:     PPU
Epochs paid: 30
Expires:     6/18/2026, 3:02:29 PM (29 epochs remaining)
Auto-renew:  On

--format json includes the same fields (paymentType, epochsPaid, ppuEpochEnd, walrusEpochEnd, hotUntil, autoRenew) on the response object.

opentusk file delete <file-ids...>

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

Flag	Description
--yes	Skip confirmation prompt

opentusk file delete abc123 --yes
opentusk file delete abc123 def456 --yes

opentusk file move <file-id>

Move a file to a different folder, or back to vault root.

Flag	Description
--folder <folder-id>	Target folder ID
--root	Move to vault root (no folder)

opentusk file retry [file-ids...]

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

opentusk file retry                        # Retry all errored files
opentusk file retry abc123 def456          # Retry specific files

opentusk file extend <file-id>

Extend a PPU file’s Walrus lifetime by purchasing additional epochs. Uses the same on-chain 402 flow as PPU upload: the CLI signs a WAL transfer, the API records the payment, and a worker job calls Walrus extendBlob to advance ppuEpochEnd, hotUntil, and walrusEpochEnd. Only paymentType: 'ppu' files that are already synced to Walrus and not yet expired can be extended.

Flag	Description
--epochs <n>	(required) Number of additional epochs (~24 h each) to purchase
--yes	Auto-confirm payment prompts

opentusk file auto-renew <file-id>

Toggle auto-renewal for a file’s Walrus storage.

Flag	Description
--on	Enable auto-renew
--off	Disable auto-renew

opentusk file 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 shared vault.

Flag	Description
--output <path>	Output file path (defaults to blob-<blobId> in current directory)
--stdout	Write blob content to stdout instead of a file

opentusk file rehydrate Bx7K9...abc --output myfile.enc
opentusk file rehydrate Bx7K9...abc --stdout

---

Upload and download

opentusk upload <paths...>

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

Flag	Description
--vault <vault>	Target vault (ID, slug, or name). Falls back to the default vault.
--folder <folder-id>	Target folder ID within the vault
--recursive	Upload directory contents recursively
--content <text>	Upload inline text content instead of a file path
--stdin	Read file content from stdin
--name <filename>	File name to use (required with --content or --stdin)
--ppu	Bill this upload to your Sui wallet (pay-per-upload). Bypasses the plan’s storage quota and file-size cap (up to the 100 MB PPU max), and includes Walrus durability. Only available on plans where plan.ppuEnabled === true — currently the Free tier. Returns 403 on paid plans.
--epochs <n>	PPU only: number of Walrus epochs (~24 h each) to pay for. Defaults to 30.
--yes	Auto-confirm payment prompts
--wait	Wait for Walrus sync after upload

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

# Pay-per-upload on the Free plan — bill this file in WAL on Sui, bypass
# the 10 MB plan cap, and get Walrus durability included.
opentusk upload report.pdf --vault my-vault --ppu --epochs 30 --yes

# Sandbox / agent mode (no filesystem needed)
opentusk upload --content "hello world" --name notes.txt --vault my-vault
echo "hello" | opentusk upload --stdin --name notes.txt --vault my-vault

# Wait for Walrus sync
opentusk upload photo.jpg --vault my-vault --wait

opentusk download <file-id>

Download a file. For shared vaults, SEAL decryption is handled automatically (requires OPENTUSK_SUI_PRIVATE_KEY env var). 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)
--stdout	Write file content to stdout instead of a file

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

# Sandbox / agent mode — pipe to stdout
opentusk download abc123 --stdout
opentusk download abc123 --stdout > myfile.pdf

---

Folders

opentusk folder create <name>

Create a folder in a vault.

Flag	Description
--vault <vault>	(required) Target vault (ID, slug, or name)
--parent <parent-id>	Parent folder ID (for nested folders)

opentusk folder create "Documents" --vault my-vault
opentusk folder create "Invoices" --vault my-vault --parent <parent-folder-id>

opentusk folder list

List folders in a vault.

Flag	Description
--vault <vault>	(required) Target vault (ID, slug, or name)
--parent <parent-id>	List children of a specific parent folder

opentusk folder info <folder-id>

Show folder details — name, ID, vault, parent, and creation date.

opentusk folder contents <folder-id>

List folder contents (files and subfolders) in a single view.

opentusk folder rename <folder-id> <new-name>

Rename a folder.

opentusk folder delete <folder-id>

Delete a folder. The folder must be empty. Prompts for confirmation unless --yes is passed.

Flag	Description
--yes	Skip confirmation prompt

---

Trash

opentusk trash list

List trashed files and vaults. Also runs when you type opentusk trash with no subcommand. Items are permanently deleted after 7 days.

opentusk trash restore <id>

Restore a trashed item (file or vault) by ID.

opentusk trash delete <id>

Permanently delete a single trashed item. This cannot be undone.

Flag	Description
--yes	Skip confirmation prompt

opentusk trash empty

Permanently delete all trashed items. This cannot be undone.

Flag	Description
--yes	Skip confirmation prompt

---

Webhooks

opentusk webhook create <url>

Create a webhook endpoint.

Flag	Description
--events <events>	(required) Comma-separated list of events to subscribe to
--description <text>	Webhook description

opentusk webhook create https://example.com/hook --events file.synced,file.error

Caution

Save the secret from the output. It’s only shown once and is required to verify webhook signatures.

opentusk webhook list

List all webhook endpoints with URL, event count, active status, and failure count.

opentusk webhook info <webhook-id>

Show webhook endpoint details — URL, events, description, failure count, last delivery status.

opentusk webhook update <webhook-id>

Update a webhook endpoint.

Flag	Description
--url <url>	New webhook URL
--events <events>	Comma-separated list of events
--active <bool>	Enable or disable (true/false)
--description <text>	New description

opentusk webhook delete <webhook-id>

Delete a webhook endpoint. Prompts for confirmation unless --yes is passed.

Flag	Description
--yes	Skip confirmation prompt

opentusk webhook test <webhook-id>

Send a test delivery to verify your endpoint is reachable.

opentusk webhook deliveries <webhook-id>

List recent deliveries for a webhook — event, status, HTTP code, attempts.

Flag	Description	Default
--limit <n>	Max results	20

---

Semantic search

Search commands require the @opentusk/indexer package. Install it separately to keep the core CLI lightweight:

npm install -g @opentusk/indexer

See the Semantic Search guide for how indexing works, what gets indexed, and the stdio vs HTTP daemon trade-off.

opentusk index setup

Pick an embedding model, download it (~80 MB for all-MiniLM-L6-v2), and initialize the local SQLite database at ~/.opentusk/index/. Interactive by default — prompts you to choose a model. Run once per machine.

Flag	Description
--model <key>	Skip the prompt and use this model key
--non-interactive	Use the configured (or default) model without prompting

opentusk index sync

Catch-up sync for the local index. Files uploaded through this CLI or the MCP server are indexed live while the indexer is running, so you mostly only need this to pick up files uploaded from the web app, the SDK, or other clients — or after starting a fresh index. Incremental by default: only un-indexed files get processed.

Flag	Description
--vault <vault-id>	Sync a specific vault only
--full	Re-walk every file even if already in the index (picks up edits to already-indexed files)
--include-binary	Download bodies for files classified as non-indexable (images, video, archives). By default these get a metadata-only entry.
--sniff-limit <bytes>	Size cap for octet-stream / unknown-MIME downloads. Above this they become metadata-only. Default 1 MiB.

opentusk index reset

Drop the index database and start over. Useful after switching embedding models or recovering from a corrupted index.

Flag	Description
--yes	Skip confirmation prompt

opentusk index stats

Show index statistics — documents, chunks, vaults, DB size, and last-indexed timestamp.

Flag	Description
--json	Output raw JSON

opentusk search <query>

Run a semantic query across indexed files.

Flag	Description	Default
--vault <vault-id>	Filter by vault ID	—
--folder <path>	Folder path prefix (recursive)	—
--type <mime>	MIME type filter, e.g. application/pdf	—
--limit <n>	Max results	10
--min-score <n>	Similarity threshold 0–1	0.3
--json	Output raw JSON	—

opentusk search "deployment runbook"
opentusk search "invoice Acme Q1" --vault abc123 --limit 5
opentusk search "design doc" --type application/pdf --min-score 0.5

---

MCP server

opentusk 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.

opentusk 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	—
--sui-priv-key <key>	Sui Ed25519 private key for SEAL encryption	stored key

---

Disaster recovery

opentusk export

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

Flag	Description	Default
-o, --output <path>	Output file path	opentusk-export.json
--stdout	Write JSON manifest to stdout instead of a file	—
--vault <vaultId>	Export only a specific vault	all vaults

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

# Sandbox / agent mode — pipe to stdout
opentusk export --stdout
opentusk export --stdout > backup.json

---

Interactive TUI

opentusk tui

Launch a full-screen interactive terminal UI for browsing and managing your storage.

Features:

• Browse owned vaults and shared vaults you’re a member of
• Navigate folder hierarchies within vaults
• Upload files and download files directly from the TUI
• Manage trash — view, restore, and permanently delete trashed items
• View file details, statuses, and Walrus metadata

---

Agent usage guide

The CLI is designed for AI agents running in sandboxed environments (Claude Desktop, Claude Code, CI pipelines) where there may be no writable filesystem, no persistent config, and no interactive terminal.

Environment variables

Variable	Purpose
OPENTUSK_API_KEY	API key — no config file needed
OPENTUSK_API_URL	Override API URL (default: https://api.opentusk.ai)
OPENTUSK_SUI_PRIVATE_KEY	Sui private key for shared vault SEAL encryption
OPENTUSK_PASSWORD	Master passphrase for private vault decryption
OPENTUSK_INDEXER_URL	HTTP indexer daemon URL (e.g. http://localhost:7600). If unset, the CLI spawns the indexer over stdio.

--format json output

Every command supports --format json. Output shape:

{ "success": true, "data": { ... } }

Error shape:

{ "success": false, "error": "message", "code": "NOT_FOUND" }

Exit codes

Code	Meaning
0	Success
1	General error
2	Not found
3	Authentication error
4	Payment required

--yes — skip all prompts

All destructive commands accept --yes to skip interactive confirmation prompts:

opentusk file delete <id> --yes
opentusk vault delete <vault> --yes
opentusk trash empty --yes
opentusk vault members remove <vault> <id> --yes

--wait — poll for async completion

For operations that trigger background jobs, --wait blocks until the job finishes:

opentusk file status <id> --wait        # wait until synced or error
opentusk upload photo.jpg --wait        # wait for Walrus sync after upload

Machine-readable IDs

opentusk vault create "My Vault" --format json | jq .data.id
opentusk upload file.txt --format json | jq .data.fileId
opentusk file info <id> --format json | jq .data.status

Full sandbox workflow (no filesystem)

export OPENTUSK_API_KEY=otk_...
export OPENTUSK_SUI_PRIVATE_KEY=suiprivkey1...  # for shared vaults

# Upload inline content (no file on disk needed)
opentusk upload --content "hello world" --name notes.txt --vault my-vault

# Download to stdout
opentusk download <file-id> --stdout

# Export manifest to stdout
opentusk export --stdout

# Rehydrate from Walrus to stdout
opentusk file rehydrate <blobId> --stdout

All spinner and progress output goes to stderr when --stdout is used, so stdout carries only the file data.

---

Deprecated commands

The following top-level commands still work but will be removed in a future release. Use the new namespaced versions.

Old command	New command
opentusk info <id>	opentusk file info <id>
opentusk status <id>	opentusk file status <id>
opentusk rm <ids...>	opentusk file delete <ids...>
opentusk mv <id>	opentusk file move <id>
opentusk retry [ids...]	opentusk file retry [ids...]
opentusk extend <id>	opentusk file extend <id>
opentusk auto-renew <id>	opentusk file auto-renew <id>
opentusk rehydrate <blob>	opentusk file rehydrate <blob>
opentusk sui setup <key>	opentusk account setup-sui <key>
opentusk sui show	opentusk account show-sui
opentusk sui clear	opentusk account clear-sui
opentusk api-keys list	opentusk account api-keys list
opentusk api-keys create <name>	opentusk account api-keys create <name>
opentusk api-keys revoke <id>	opentusk account api-keys revoke <id>

MCP tools Full reference for all 34 MCP tools.

Encryption How SEAL encryption works for shared vaults.