Search

SearchSearch

Pubky CLI

Jan 30, 20264 min read

Pubky CLI

Pubky CLI is a command-line tool for interacting with Pubky homeservers. Built in Rust, it provides both user-facing and administrative capabilities for managing homeservers, testing deployments, and automating workflows.

Overview

Pubky CLI wraps the official Pubky SDK and provides:

  • User Operations: Signup, signin, data management, session handling
  • Admin Operations: User management, server stats, invite token generation
  • Testing Tools: Integration with pubky-testnet for local development
  • Automation: Script-friendly interface for CI/CD and deployment automation

Installation

From Crates.io

cargo install pubky-cli

From Source

git clone https://github.com/pubky/pubky-cli
cd pubky-cli
cargo install --path .

Verify Installation

pubky-cli --version

Quick Start

Create Recovery File

Recovery files store encrypted identity keys:

# Generate recovery file with passphrase
pubky-cli tools generate-recovery ./alice.recovery --passphrase mypass
 
# Prints the public key
# Example: z4e8s17cou9qmuwen8p1556jzhf1wktmzo6ijsfnri9c4hnrdfty

User Signup

# Sign up with homeserver (testnet)
PUBKY_CLI_RECOVERY_PASSPHRASE=mypass \
  pubky-cli user signup <homeserver-pubkey> ./alice.recovery --testnet
 
# With signup code (for gated servers)
PUBKY_CLI_RECOVERY_PASSPHRASE=mypass \
  pubky-cli user signup --signup-code <code> <homeserver-pubkey> ./alice.recovery --testnet

Admin Operations

# Get server info
PUBKY_ADMIN_PASSWORD=admin \
  pubky-cli admin info
 
# Generate signup token
PUBKY_ADMIN_PASSWORD=admin \
  pubky-cli admin generate-token

User Commands

Authentication

# Sign in
PUBKY_CLI_RECOVERY_PASSPHRASE=mypass \
  pubky-cli user signin ./alice.recovery --testnet
 
# Check session
PUBKY_CLI_RECOVERY_PASSPHRASE=mypass \
  pubky-cli user session ./alice.recovery --testnet
 
# Sign out
PUBKY_CLI_RECOVERY_PASSPHRASE=mypass \
  pubky-cli user signout ./alice.recovery --testnet

Data Management

# Publish data from file
PUBKY_CLI_RECOVERY_PASSPHRASE=mypass \
  pubky-cli user publish "/pub/myapp/data.json" ./local-file.json ./alice.recovery --testnet
 
# Get data by path
PUBKY_CLI_RECOVERY_PASSPHRASE=mypass \
  pubky-cli user get "/pub/myapp/data.json" ./alice.recovery --testnet
 
# List directory
PUBKY_CLI_RECOVERY_PASSPHRASE=mypass \
  pubky-cli user list "/pub/myapp/" ./alice.recovery --testnet
 
# Delete data
PUBKY_CLI_RECOVERY_PASSPHRASE=mypass \
  pubky-cli user delete "/pub/myapp/data.json" ./alice.recovery --testnet

Admin Commands

User Management

# Disable user
PUBKY_ADMIN_PASSWORD=admin \
  pubky-cli admin user disable <user-pubkey>
 
# Enable user
PUBKY_ADMIN_PASSWORD=admin \
  pubky-cli admin user enable <user-pubkey>
 
# Delete user data
PUBKY_ADMIN_PASSWORD=admin \
  pubky-cli admin user delete <user-pubkey> /path/to/file

Server Operations

# Get server statistics
PUBKY_ADMIN_PASSWORD=admin \
  pubky-cli admin info
 
# Generate invite/signup token
PUBKY_ADMIN_PASSWORD=admin \
  pubky-cli admin generate-token

Environment Variables

VariablePurposeExample
PUBKY_ADMIN_PASSWORDAdmin API passwordadmin
PUBKY_CLI_RECOVERY_PASSPHRASEAuto-decrypt recovery filesmypassphrase
PUBKY_PKARR_BOOTSTRAPOverride PKARR bootstrap nodesnode1.example.com:6881,node2.example.com:6881
PUBKY_PKARR_RELAYSCustom PKARR relay URLshttps://relay1.example.com,https://relay2.example.com
PUBKY_PKARR_TIMEOUT_MSPKARR request timeout5000

Shell Completions

Generate tab completion scripts for your shell:

# Bash
pubky-cli tools completions bash --outfile "$(brew --prefix)/etc/bash_completion.d/pubky-cli"
 
# Zsh
mkdir -p ~/.zfunc
pubky-cli tools completions zsh --outfile ~/.zfunc/_pubky-cli
echo 'fpath+=("$HOME/.zfunc")' >> ~/.zshrc
 
# Fish
pubky-cli tools completions fish --outfile ~/.config/fish/completions/pubky-cli.fish
 
# PowerShell
pubky-cli tools completions powershell --outfile $PROFILE/../Completions/pubky-cli.ps1

Supported shells: bash, zsh, fish, powershell, elvish

Testing & CI

Local Testing

# Run all tests (includes integration tests)
cargo test
 
# Test uses pubky-testnet internally - no external setup needed

Example Workflow

#!/bin/bash
# Automated user onboarding script
 
# 1. Generate recovery file
pubky-cli tools generate-recovery ./user.recovery --passphrase $PASSWORD
 
# 2. Sign up
PUBKY_CLI_RECOVERY_PASSPHRASE=$PASSWORD \
  pubky-cli user signup $HOMESERVER_PK ./user.recovery --testnet
 
# 3. Sign in
PUBKY_CLI_RECOVERY_PASSPHRASE=$PASSWORD \
  pubky-cli user signin ./user.recovery --testnet
 
# 4. Publish initial profile
PUBKY_CLI_RECOVERY_PASSPHRASE=$PASSWORD \
  pubky-cli user publish "/pub/pubky.app/profile.json" ./profile.json ./user.recovery --testnet
 
echo "User onboarded successfully!"

Use Cases

Local Development

Test homeserver functionality without building custom clients:

# Start local homeserver
cargo run -p pubky-homeserver -- --data-dir ~/.pubky
 
# Test with CLI
pubky-cli admin info

Deployment Automation

Script homeserver configuration and user provisioning:

# Generate batch signup tokens
for i in {1..100}; do
  PUBKY_ADMIN_PASSWORD=$ADMIN_PASS pubky-cli admin generate-token >> tokens.txt
done

Integration Testing

Validate end-to-end flows in CI:

# CI test script
cargo test --all

Homeserver Administration

Manage users and monitor server health:

# Disable abusive user
PUBKY_ADMIN_PASSWORD=admin pubky-cli admin user disable $ABUSER_KEY
 
# Check server stats
PUBKY_ADMIN_PASSWORD=admin pubky-cli admin info

Architecture

Project Structure

pubky-cli/
├── src/
│   ├── admin.rs      # Admin API wrapper
│   ├── user.rs       # User operations (via Pubky SDK)
│   ├── tools.rs      # Utilities (recovery, completions)
│   ├── util.rs       # Shared helpers
│   └── main.rs       # CLI entry point
├── tests/
│   └── integration.rs # E2E tests with pubky-testnet
└── Cargo.toml

Dependencies

  • pubky SDK (0.6.0-rc.6): User-facing operations
  • pubky-testnet: Local testing harness
  • clap: Command-line argument parsing
  • tokio: Async runtime

Troubleshooting

Connection Issues

# Verify homeserver is running
curl http://127.0.0.1:6287/
 
# Check admin API
curl http://127.0.0.1:6288/

Recovery File Errors

# Ensure passphrase is correct
PUBKY_CLI_RECOVERY_PASSPHRASE=wrong-pass pubky-cli user signin ./alice.recovery
# Error: Failed to decrypt recovery file
 
# Use correct passphrase
PUBKY_CLI_RECOVERY_PASSPHRASE=correct-pass pubky-cli user signin ./alice.recovery
# Success

Testnet vs Production

# Testnet (local development)
pubky-cli user signup $HOMESERVER_PK ./recovery --testnet
 
# Production (requires full homeserver URL)
pubky-cli user signup $HOMESERVER_PK ./recovery

Graph View