cli

module
v0.1.7-alpha.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 22, 2026 License: MIT

README

XenForo CLI (xf)

A command-line tool for provisioning and managing XenForo development environments with Docker.

Requirements

  • Go
  • Docker with Docker Compose plugin
  • Git
  • System keychain
    • macOS Keychain
    • Windows Credential Manager
    • Linux Secret Service

Quick Start

# Build locally
make build

# Authenticate
./xf auth login

# Initialize a project
./xf init ./my-project

# Show all built-in xf commands
./xf --help

Install for Local Use

# Installs into $(go env GOBIN) or $(go env GOPATH)/bin
go install .

# Verify
xf version

Command Routing

xf supports two command types:

  1. Built-in commands such as xf init, xf up, xf auth login.
  2. XenForo commands: if the first token is not a built-in command, xf forwards it to XenForo inside Docker. If Docker config is not initialized (no compose.yaml), xf falls back to local execution as php cmd.php <args...>.

Use this to discover available XenForo commands:

# Run from a XenForo directory (or set XF_DIR)
xf list

# Run a XenForo command directly
xf xf-dev:import

If you are not in a XenForo directory, set XF_DIR to a directory that contains src/XF.php.

CLI Usage

Authentication
# Log in
xf auth login

# Log in with a custom browser callback timeout (seconds)
xf auth login --timeout 600

# Check auth status
xf auth status
xf auth status --json

# Refresh token
xf auth refresh

# Log out and revoke tokens
xf auth logout
Initialize
# Interactive init
xf init ./my-project

# Interactive flow notes:
# - XenForo core is always installed
# - You choose only additional products
# - Core version picker shows the latest 10 versions + manual entry
# - A final review screen lets you edit all values before work starts

# Non-interactive init
xf init ./my-project \
  --license 02306C2650 \
  --version 2030871 \
  --products xfmg,xfes \
  --admin-user admin \
  --admin-password secret \
  --admin-email admin@example.com

# Existing directory mode
xf init ./existing-xf-project --existing
xf init ./existing-xf-project --existing --up

# .env overrides (file + inline; inline wins)
xf init ./my-project \
  --env-file ./my.env \
  --env XF_TITLE="My Site"

# Note: init defaults XF_DEBUG=1 and XF_DEVELOPMENT=1.
# You can override either key via --env-file/--env.
Upgrade
# Interactive upgrade
xf upgrade ./my-project

# Upgrade to a specific version
xf upgrade ./my-project --version 2030971

# Skip running xf:upgrade
xf upgrade ./my-project --version 2030971 --skip-upgrade
Download Packages
# List downloads for a license
xf download --license 02306C2650

# List versions for a product
xf download --license 02306C2650 --download xenforo

# Download a specific version
xf download --license 02306C2650 --download xenforo --version 12345

# Force re-download even if cached
xf download --license 02306C2650 --download xenforo --version 12345 --force
Cache
xf cache list
xf cache list --license 02306C2650
xf cache list --json
xf cache purge --license 02306C2650
xf cache purge --all
xf cache path
Docker Environment
# Lifecycle
xf up
xf down
xf reboot

# Status and logs
xf ps
xf logs
xf logs --follow

# Docker Compose passthrough
xf compose -- ps
xf compose -- exec xf mysql -u root

# Exec into a service
xf exec xf ls -la
PHP / Composer / Debug
# PHP and Composer
xf php -- -v
xf composer -- install

# XenForo command with XDebug enabled
xf debug xf-dev:import

# PHP with XDebug enabled
xf php-debug -- -v
Other Commands
xf licenses
xf doctor
xf self-update
xf self-update --check-only
xf version
xf version --json
xf version --short
Shell Completion
# Example: zsh
xf completion zsh
Global Flags

Available on all built-in commands:

--non-interactive      # Disable prompts (for CI/automation)
-v, --verbose          # Enable verbose output

Data and Paths

  • Config: ~/.config/xf/config.json
  • Cache: ~/.config/xf/cache
  • Project metadata file: .xf.json
  • OAuth token storage: system keychain service xf

Development Commands

Make
make build      # Build the binary
make run        # Run without building (go run)
make test       # Run all tests
make test-v     # Run tests with verbose output
make test-cover # Run tests with coverage
make fmt        # Format code
make vet        # Check for common mistakes
make tidy       # Update dependencies
make clean      # Remove built binary
make all        # Format, vet, test, and build
Go Directly
# Build
go build -o xf .

# Run without building
go run . --help
go run . version

# Tests
go test ./...
go test ./... -v
go test ./... -cover

Project Structure

xf/
├── cmd/                    # CLI commands
├── internal/
│   ├── api/                # XenForo API client
│   ├── auth/               # OAuth and keychain integration
│   ├── cache/              # Download cache management
│   ├── config/             # Config and environment settings
│   ├── dockercompose/      # Docker Compose runner integration
│   ├── doctor/             # System diagnostics
│   ├── downloads/          # Download orchestration
│   ├── embed/              # Embedded Docker assets
│   ├── errors/             # Structured error types
│   ├── extract/            # Archive extraction
│   ├── selfupdate/         # Self-update logic
│   ├── stream/             # Streaming/progress helpers
│   ├── ui/                 # CLI UI helpers
│   ├── version/            # Build/runtime version info
│   ├── xf/                 # XenForo-specific helpers
│   └── xfcmd/              # XenForo command helpers
├── scripts/                # Install/test scripts
├── main.go                 # Entry point
├── go.mod                  # Go module definition
├── Makefile                # Build automation
└── README.md

Security

  • OAuth tokens are stored only in the system keychain (no plaintext file fallback).
  • PKCE is used for OAuth authorization flow security.
  • Tokens are refreshed automatically when needed.

Building for Release

# Build with embedded version information
make release VERSION=1.0.0

Directories

Path Synopsis
cmd
xf command
Package main provides the CLI entry point.
Package main provides the CLI entry point.
internal
auth
Package auth handles authentication and OAuth flows.
Package auth handles authentication and OAuth flows.
cache
Package cache manages downloaded files and their metadata.
Package cache manages downloaded files and their metadata.
config
Package config manages CLI configuration and settings.
Package config manages CLI configuration and settings.
customerapi
Package customerapi provides an authenticated HTTP client for the XenForo Customer API.
Package customerapi provides an authenticated HTTP client for the XenForo Customer API.
docker
Package docker contains embedded Docker files and extraction utilities.
Package docker contains embedded Docker files and extraction utilities.
dockercompose
Package dockercompose provides Docker Compose CLI operations for XenForo.
Package dockercompose provides Docker Compose CLI operations for XenForo.
doctor
Package doctor provides health checks for CLI dependencies and configuration.
Package doctor provides health checks for CLI dependencies and configuration.
downloads
Package downloads handles product and add-on download selection and retrieval.
Package downloads handles product and add-on download selection and retrieval.
extract
Package extract provides utilities for extracting zip files.
Package extract provides utilities for extracting zip files.
initflow
Package initflow provides interactive workflow builders for setup tasks.
Package initflow provides interactive workflow builders for setup tasks.
selfupdate
Package selfupdate provides CLI self-update functionality using GitHub releases.
Package selfupdate provides CLI self-update functionality using GitHub releases.
stream
Package stream provides utilities for tracking download and streaming progress.
Package stream provides utilities for tracking download and streaming progress.
testutils
Package testutils provides testing utilities for the CLI.
Package testutils provides testing utilities for the CLI.
ui
Package ui provides formatting and styling utilities for console output.
Package ui provides formatting and styling utilities for console output.
version
Package version provides CLI version information.
Package version provides CLI version information.
xf
Package xf provides utilities for XenForo installation detection and management.
Package xf provides utilities for XenForo installation detection and management.
xfcmd
Package xfcmd provides high-level commands for managing XenForo installations.
Package xfcmd provides high-level commands for managing XenForo installations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL