CLI Reference

The Roset CLI is the operator's interface for managing files, searching content, and diagnosing issues from the terminal.

Installation

Install with Go:

bash

go install github.com/rosetdata/roset/cli@latest

Or download a prebuilt binary from the releases page.

Configuration

The CLI stores credentials in ~/.roset/config.yaml (permissions 0600):

yaml

api_url: "https://api.roset.dev"
api_key: "rsk_..."

Precedence

Configuration is resolved in this order (highest priority first):

CLI flags — --api-key, --verbose, --json
Environment variables — ROSET_API_KEY, ROSET_API_URL, ROSET_DEBUG
Config file — ~/.roset/config.yaml
Defaults — https://api.roset.dev, no key

Environment Variables

Variable	Description
`ROSET_API_KEY`	Override API key from config
`ROSET_API_URL`	Override API URL (default: `https://api.roset.dev`)
`ROSET_DEBUG`	Enable debug mode

Global Flags

These flags are available on all commands:

Flag	Type	Default	Description
`--json`	bool	`false`	Output in JSON format (machine-readable)
`--verbose`	bool	`false`	Enable verbose logging
`--api-key`	string		Roset API key (overrides config and env)

Commands

Authenticate with the Roset API. Opens an interactive prompt for your API key.

bash

roset login

The CLI validates your key against the API and saves credentials to ~/.roset/config.yaml. The API key input is masked for security.

roset logout

Remove stored credentials and configuration.

bash

roset logout

Deletes ~/.roset/config.yaml. Safe to call when already logged out.

roset upload

Upload a local file to a remote path. Roset returns a signed upload URL — the file bytes go directly to storage, never through Roset.

bash

roset upload <local-file> <remote-path>

Argument	Required	Description
`local-file`	Yes	Path to local file on disk
`remote-path`	Yes	Destination path in Roset

Example:

bash

roset upload ./report.pdf documents/report.pdf

Output includes the signed upload URL and the created node ID. After uploading to the signed URL, the file enters the processing pipeline automatically.

roset ls

List files and folders at a path.

bash

roset ls [path]

Argument	Required	Description
`path`	No	Path to list (default: `/`)

Example:

bash

# List root
roset ls
 
# List a specific folder
roset ls documents/
 
# JSON output
roset ls --json documents/

Displays a table with columns: TYPE, NAME, SIZE, UPDATED.

roset download

Get a signed download URL for a file node. The URL points directly to the storage provider.

bash

roset download <node-id>

Argument	Required	Description
`node-id`	Yes	UUID of the file node

Example:

bash

roset download abc-123-def

roset search

Search files by content using full-text, vector similarity, or hybrid search.

bash

roset search <query> [flags]

Argument	Required	Description
`query`	Yes	Search query string

Flag	Short	Type	Default	Description
`--mode`	`-m`	string	`hybrid`	Search mode: `text`, `vector`, or `hybrid`
`--space`	`-s`	string		Scope search to a specific space
`--limit`	`-l`	int	`20`	Maximum number of results

Example:

bash

# Hybrid search (default)
roset search "payment terms"
 
# Full-text search in a specific space
roset search "quarterly revenue" --mode text --space finance
 
# JSON output for scripting
roset search "API endpoints" --json --limit 5

roset qa

Ask a question about your files using RAG (Retrieval Augmented Generation). Returns an answer with source citations.

bash

roset qa <question> [flags]

Argument	Required	Description
`question`	Yes	Question to ask

Flag	Short	Type	Default	Description
`--space`	`-s`	string		Scope Q&A to a specific space
`--top-k`	`-k`	int	`5`	Number of context documents to retrieve

Example:

bash

# Ask a question across all files
roset qa "What are the payment terms?"
 
# Scope to a space with more context
roset qa "Summarize the Q3 results" --space finance --top-k 10
 
# JSON output
roset qa "What is the refund policy?" --json

roset status

Show current configuration and test API connectivity.

bash

roset status

Displays:

API URL and key status (masked)
Connection status with latency
System information (OS, architecture, Go version)

Example output:

Roset CLI Status
────────────────────────────────────────
API URL:         https://api.roset.dev
API Key:         rsk_****...****a1b2

API Status:      ● Connected (45ms)

System:          darwin/arm64
Go Version:      go1.22.0

roset config doctor

Diagnose configuration issues. Checks file permissions, environment overrides, and missing settings.

bash

roset config doctor

Checks performed:

Config file existence at ~/.roset/config.yaml
File permissions (should be 0600)
Environment variable overrides
API key presence

roset debug bundle

Create a diagnostic bundle for troubleshooting. Collects system information and logs into a gzipped tar archive with automatic secret redaction.

bash

roset debug bundle [flags]

Flag	Short	Type	Default	Description
`--output`	`-o`	string	`roset-debug-{timestamp}.tar.gz`	Output path for the bundle
`--no-redact`		bool	`false`	Disable secret redaction

Caution

The --no-redact flag disables secret redaction. The resulting bundle may contain API keys and other secrets. Do not share unredacted bundles with unauthorized parties.

The bundle includes:

system_info.json — OS, architecture, filtered environment variables
logs/ — last 1000 lines from system logs

roset version

Print version information.

bash

roset version

Example output:

Roset CLI

Version:     1.0.0
Commit:      abc1234
Built:       2026-01-15T10:00:00Z

roset completion

Generate shell completion scripts.

bash

roset completion [bash|zsh|fish|powershell]

Bash:

bash

# Source directly
source <(roset completion bash)
 
# Install persistently (Linux)
roset completion bash > /etc/bash_completion.d/roset
 
# Install persistently (macOS with Homebrew)
roset completion bash > $(brew --prefix)/etc/bash_completion.d/roset

Zsh:

bash

echo "autoload -U compinit; compinit" >> ~/.zshrc
roset completion zsh > "${fpath[1]}/_roset"

Fish:

bash

roset completion fish > ~/.config/fish/completions/roset.fish

CLI Reference

Installation#

Configuration#

Precedence#

Environment Variables#

Global Flags#

Commands#

roset login#

roset logout#

roset upload#

roset ls#

roset download#

roset search#

roset qa#

roset status#

roset config doctor#

roset debug bundle#

roset version#

roset completion#

Installation

Configuration

Precedence

Environment Variables

Global Flags

Commands

roset login

roset logout

roset upload

roset ls

roset download

roset search

roset qa

roset status

roset config doctor

roset debug bundle

roset version

roset completion