Skip to content

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

Section titled “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

Section titled “Installation”

From Crates.io

Section titled “From Crates.io”
Terminal window
cargo install pubky-cli

From Source

Section titled “From Source”
Terminal window
git clone https://github.com/pubky/pubky-cli
cd pubky-cli
cargo install --path .

Verify Installation

Section titled “Verify Installation”
Terminal window
pubky-cli --version

Quick Start

Section titled “Quick Start”

Create Recovery File

Section titled “Create Recovery File”

Recovery files store encrypted identity keys:

Terminal window
# Generate recovery file with passphrase
pubky-cli tools generate-recovery ./alice.recovery --passphrase mypass


# Prints the public key
# Example: z4e8s17cou9qmuwen8p1556jzhf1wktmzo6ijsfnri9c4hnrdfty

User Signup

Section titled “User Signup”
Terminal window
# 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

Section titled “Admin Operations”
Terminal window
# 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

Section titled “User Commands”

Authentication

Section titled “Authentication”
Terminal window
# 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

Section titled “Data Management”
Terminal window
# 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

Section titled “Admin Commands”

User Management

Section titled “User Management”
Terminal window
# 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

Section titled “Server Operations”
Terminal window
# 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

Section titled “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

Section titled “Shell Completions”

Generate tab completion scripts for your shell:

Terminal window
# 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

Section titled “Testing & CI”

Local Testing

Section titled “Local Testing”
Terminal window
# Run all tests (includes integration tests)
cargo test


# Test uses pubky-testnet internally - no external setup needed

Example Workflow

Section titled “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

Section titled “Use Cases”

Local Development

Section titled “Local Development”

Test Homeserver functionality without building custom clients:

Terminal window
# Start local homeserver
cargo run -p pubky-homeserver -- --data-dir ~/.pubky


# Test with CLI
pubky-cli admin info

Deployment Automation

Section titled “Deployment Automation”

Script Homeserver configuration and user provisioning:

Terminal window
# 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

Section titled “Integration Testing”

Validate end-to-end flows in CI:

Terminal window
# CI test script
cargo test --all

Homeserver Administration

Section titled “Homeserver Administration”

Manage users and monitor server health:

Terminal window
# 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

Section titled “Architecture”

Project Structure

Section titled “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

Section titled “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

Section titled “Troubleshooting”

Connection Issues

Section titled “Connection Issues”
Terminal window
# Verify homeserver is running
curl http://127.0.0.1:6287/


# Check admin API
curl http://127.0.0.1:6288/

Recovery File Errors

Section titled “Recovery File Errors”
Terminal window
# 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

Section titled “Testnet vs Production”
Terminal window
# Testnet (local development)
pubky-cli user signup $HOMESERVER_PK ./recovery --testnet


# Production (requires full homeserver URL)
pubky-cli user signup $HOMESERVER_PK ./recovery
Section titled “Links”
Section titled “Related Documentation”