CLI Reference Overview

Overview

The FastSkill CLI provides a comprehensive command-line interface for managing skills, running the service, and performing administrative tasks. It’s designed for both development workflows and production operations.

The CLI supports both interactive and scripting use cases, with comprehensive help text and validation for all commands.

Installation

The FastSkill CLI is a Rust-based command-line tool. Install it using Cargo:

# From crates.io (when published)
cargo install fastskill --features git-support

# Or from source
git clone https://github.com/gofastskill/fastskill.git
cd fastskill/rust
cargo install --path . --bin fastskill --features git-support

# Verify installation
fastskill --version

Requirements:

Rust 1.70+ (rustup install stable)
Git (optional, only needed with --features git-support)

Basic Usage

Get Help

General help

fastskill --help

This shows all available commands and global options.

Command-specific help

fastskill serve --help        # Help for serve command
fastskill register --help     # Help for register command
fastskill list --help         # Help for list command

Interactive help

fastskill --interactive       # Interactive mode with guided setup

Global Options

Option	Description	Example
`--version`	Show version information	`fastskill --version`
`--verbose, -v`	Enable verbose output	`fastskill -v list`
`--quiet, -q`	Suppress non-error output	`fastskill -q register skill.json`
`--config`	Specify configuration file	`fastskill --config prod.json serve`
`--log-level`	Set logging level	`fastskill --log-level DEBUG serve`
`--help, -h`	Show help information	`fastskill --help`

Command Categories

Workspace & lifecycle

fastskill init

Create skill-project.toml for a skill (authors).

fastskill install

Install skills from skill-project.toml (supports groups and --lock).

fastskill reindex

Rebuild the search index for semantic discovery.

fastskill serve

Start the HTTP server (use --enable-registry for the web UI).

Skills

fastskill add

Add skills from registry ID, git, zip, or local folder (supports --branch, --tag, -e, --group).

fastskill read

Retrieve skill documentation and base directory path in agent-optimized format.

fastskill list

List locally installed skills with reconciliation status (supports --json, --grid).

fastskill disable

Disable skills by ID.

fastskill remove

Remove skills by ID.

fastskill show

Show skill details and dependency tree.

fastskill update

Update skills to the latest from source.

Registry & search

fastskill search

Semantic search across installed/available skills.

fastskill registry

Manage repositories (add/list/remove/show/update/test/refresh/list-skills/show-skill/versions/search/create).

fastskill registry list-skills

List skills from HTTP registry (supports --scope, --all-versions, --include-pre-release, --json, --grid).

fastskill auth

Manage authentication for registries.

Packaging & publish

fastskill package

Package skills into ZIP artifacts (supports change detection and version bumps).

fastskill publish

Publish packaged artifacts to blob storage.

Diagnostics

fastskill version

Show CLI version.

Configuration

Configuration Files

The CLI uses .fastskill/config.yaml for service-level configuration:

.fastskill/config.yaml

embedding:
  openai_base_url: "https://api.openai.com/v1"
  embedding_model: "text-embedding-3-small"

# Optional: Custom skills directory
skills_directory: ".claude/skills"

Project-level configuration (skill dependencies and repositories) is stored in skill-project.toml at your project root:

skill-project.toml

[dependencies]
web-scraper = { source = "git", url = "https://github.com/org/web-scraper.git" }

[tool.fastskill.repositories]
[[tool.fastskill.repositories]]
name = "public-registry"
type = "http-registry"
index_url = "https://api.fastskill.io/index"
priority = 0

For publishing, create .fastskill/publish.toml:

.fastskill/publish.toml

[blob_storage]
type = "s3"
endpoint = "https://s3.example.com"
bucket = "skills-registry"
region = "us-east-1"

[registry]
git_url = "https://github.com/org/skill-registry.git"
branch = "main"
blob_base_url = "https://blob.example.com/skills"

Environment Variables

Scripting and Automation

The CLI is designed for scripting and CI/CD integration:

Batch Operations

# Add multiple local skills (editable) and install
for dir in ./skills/*; do
  fastskill add "$dir" -e --group dev
done

fastskill install
fastskill reindex

JSON Output

# Get machine-readable search results
fastskill search "text processing" --format json > skills.json

# Parse count
count=$(jq length skills.json)
echo "Total matches: $count"

Exit Codes

The CLI returns appropriate exit codes for scripting:

Code	Meaning	Example
`0`	Success	Command completed successfully
`1`	General error	Invalid arguments or configuration
`2`	Validation error	Invalid skill definition
`3`	Network error	Cannot connect to service
`4`	Timeout error	Command timed out
`5`	Permission error	Insufficient permissions

#!/bin/bash
# Minimal install + search smoke test

set -e
fastskill install
fastskill reindex
fastskill search "smoke test"

Examples

Development Workflow

# 1. Add a dev skill (editable)
fastskill add ./skills/my-skill -e --group dev

# 2. Install and index
fastskill install
fastskill reindex

# 3. Start the registry UI for browsing
fastskill serve --enable-registry --port 8080

# 4. Test search
fastskill search "text processing"

Production Deployment

# 1. Install reproducibly
fastskill install --lock

# 2. Reindex
fastskill reindex

# 3. Start service with registry UI
fastskill serve --enable-registry --port 8080

# 4. Smoke-test search
fastskill search "health check"

CI/CD Integration

# .github/workflows/test.yml
name: FastSkill CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3

    - name: Install Rust
      uses: actions-rs/toolchain@v1
      with:
        toolchain: stable

    - name: Install FastSkill
      run: |
        cd tools/fastskill/rust
        cargo install --path . --bin fastskill --features git-support

    - name: Validate skills
      run: fastskill show

    - name: Search test
      run: fastskill search "test"
      env:
        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
    - uses: actions/checkout@v3

    - name: Install Rust
      uses: actions-rs/toolchain@v1
      with:
        toolchain: stable

    - name: Deploy skills
      run: |
        cd tools/fastskill/rust
        cargo install --path . --bin fastskill --features git-support
        fastskill serve --enable-registry
      env:
        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Troubleshooting

Common Issues

Command Not Found

Path issue: Ensure FastSkill is installed and in your PATH.

# Check installation
cargo list | grep fastskill
# Or check if binary exists
which fastskill

# Verify Rust installation
rustc --version
cargo --version

# Reinstall if needed
cargo install fastskill --features git-support

Permission Errors

File permissions: Ensure you have read/write permissions for skill directories.

# Fix permissions
chmod 755 ./skills/
chmod 644 ./skills/*.json

Service permissions: Use --user flag or run with appropriate privileges for system-wide operations.

Network Issues

Port conflicts: Check if the default port (8080) is available.

# Check port usage
netstat -tlnp | grep :8080

# Use different port
fastskill serve --port 9000

Debug Mode

Enable debug mode for detailed troubleshooting:

# Enable debug logging
fastskill --log-level DEBUG serve

# Run with verbose output
fastskill -v install

Best Practices

Commit manifest and lock

Commit skill-project.toml and skills.lock together for reproducible installs.

Reindex after changes

Run fastskill reindex after adding or updating skills so search stays fresh.

Scope dev skills

Use groups (e.g., --group dev) and install with --without dev for lean production deploys.

Monitor service health

Regularly check service status and logs to ensure optimal operation.

Backup before major changes

Create backups of skill definitions before making bulk changes or updates.

The CLI provides powerful operations that can modify your skill ecosystem. Always test in a development environment before applying changes to production.

Getting Started

Configuration

Skill Management

Discovery & Routing

Tool Calling

Progressive Loading

API Reference

CLI Reference

Registry

Examples & Tutorials

Advanced Topics

Integration

Community

​Overview

​Installation

​Basic Usage

​Get Help

​Global Options

​Command Categories

​Workspace & lifecycle

fastskill init

fastskill install

fastskill reindex

fastskill serve

​Skills

fastskill add

fastskill read

fastskill list

fastskill disable

fastskill remove

fastskill show

fastskill update

​Registry & search

fastskill search

fastskill registry

fastskill registry list-skills

fastskill auth

​Packaging & publish

fastskill package

fastskill publish

​Diagnostics

fastskill version

​Configuration

​Configuration Files

​Environment Variables

​Scripting and Automation

​Batch Operations

​JSON Output

​Exit Codes

​Examples

​Development Workflow

​Production Deployment

​CI/CD Integration

​Troubleshooting

​Common Issues

​Debug Mode

​Best Practices

Overview

Installation

Basic Usage

Get Help

Global Options

Command Categories

Workspace & lifecycle

Skills

Registry & search

Packaging & publish

Diagnostics

Configuration

Configuration Files

Environment Variables

Scripting and Automation

Batch Operations

JSON Output

Exit Codes

Examples

Development Workflow

Production Deployment

CI/CD Integration

Troubleshooting

Common Issues

Debug Mode

Best Practices