openmined SyftHub CLI
The syft CLI is a standalone command-line tool for interacting with the SyftHub privacy-preserving AI platform. It provides Unix-style commands for authentication, endpoint discovery, RAG queries, and configuration management.
Quick Reference
| Command | Purpose |
|---|---|
syft login |
Authenticate with username/password |
syft logout |
Clear stored credentials |
syft ls |
List active users |
syft ls <user> |
List user's endpoints |
syft ls <user>/<endpoint> |
Show endpoint details |
syft query <target> "<prompt>" |
RAG query with streaming output |
syft config show |
Display current configuration |
syft upgrade |
Update CLI to latest version |
Authentication
# Login (prompts for credentials)
syft login
# Logout (clears tokens)
syft logout
Tokens stored in ~/.syfthub/config.json:
- Access token: 30 min TTL
- Refresh token: 7 days TTL
Browsing Endpoints
# List all active users (grid format with type icons)
syft ls
# Output: ⚡ alice/gpt-4 📦 bob/ml-papers 🔀 carol/hybrid
# List specific user's endpoints
syft ls alice
# Show endpoint details (includes README)
syft ls alice/gpt-model
# Long format (table with TYPE, VISIBILITY, STARS)
syft ls -l
syft ls --long
# JSON output (any command)
syft ls --json
Type Icons:
- ⚡ = model (LLM generation)
- 📦 = data_source (RAG retrieval)
- 🔀 = model_data_source (combined)
RAG Queries
# Basic query (streams tokens to terminal)
syft query alice/gpt "Explain quantum computing"
# JSON output
syft query alice/gpt "Hello world" --json
The query command:
- Acquires satellite tokens for the target endpoint
- Sends request to aggregator service
- Streams response tokens in real-time
Configuration Management
Config file: ~/.syfthub/config.json
# Show current config
syft config show
# Set config value
syft config set timeout 60
syft config set hub_url https://hub.syftbox.org
Aggregator Management
# Add aggregator alias
syft add aggregator prod https://aggregator.syftbox.org
syft add aggregator staging https://staging-aggregator.example.com
# List configured aggregators
syft list aggregator
# Update aggregator
syft update aggregator prod
# Remove aggregator
syft remove aggregator staging
Accounting Service Management
# Add accounting service
syft add accounting main https://accounting.example.com
# List accounting services
syft list accounting
CLI Updates
# Check and install updates
syft upgrade
# Check only (no install)
syft upgrade --check
# Auto-confirm update
syft upgrade -y
Disable auto-update checks:
export SYFT_NO_UPDATE_CHECK=1
# or
syft --no-update-check <command>
Shell Completion
syft --install-completion bash
syft --install-completion zsh
syft --install-completion fish
Completions are cached for 5 minutes.
Installation
Binary (recommended):
curl -fsSL https://raw.githubusercontent.com/OpenMined/syfthub/main/cli/install.sh | sh
# Specific version
SYFT_VERSION=1.2.0 curl -fsSL https://raw.githubusercontent.com/OpenMined/syfthub/main/cli/install.sh | sh
# Custom directory
SYFT_INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/OpenMined/syfthub/main/cli/install.sh | sh
pip:
pip install syfthub-cli
# or
uv add syfthub-cli
Common Workflows
First-time Setup
curl -fsSL https://raw.githubusercontent.com/OpenMined/syfthub/main/cli/install.sh | sh
syft login
syft ls
Discover and Query
syft ls # Browse users
syft ls alice # See alice's endpoints
syft ls alice/gpt-model # View details
syft query alice/gpt-model "Hello" # Query the model
Configure Custom Aggregator
syft add aggregator myagg https://my-aggregator.example.com
syft config set defaults.aggregator myagg
syft config show
Config File Structure
{
"access_token": "...",
"refresh_token": "...",
"aggregators": {
"prod": "https://aggregator.example.com"
},
"accounting_services": {
"main": "https://accounting.example.com"
},
"defaults": {
"aggregator": "prod"
},
"timeout": 30,
"hub_url": "https://hub.syftbox.org"
}