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 add --help          # Help for add command
fastskill list --help         # Help for list command

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). See init Command.

fastskill install

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

fastskill update

Update skills to latest from source with version strategies. See update Command.

fastskill reindex

Rebuild the search index for semantic discovery. See reindex Command.

fastskill serve

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

Skills

fastskill add

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

fastskill read

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

fastskill list

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

fastskill disable

Disable skills by ID. See skill commands.

fastskill remove

Remove skills by ID. See skill commands.

fastskill show

Show skill details and dependency tree. See skill commands.

Registry & search

fastskill search

Semantic search across installed skills (supports --format xml, --format json). See search Command.

fastskill sources

Manage repositories (list/add/remove/show/update/test/refresh/create) with authentication and priority. See sources Command.

fastskill auth

Manage authentication (login/logout/whoami) with JWT tokens and RBAC. See auth Command.

Packaging & publish

fastskill package

Package skills into ZIP artifacts with change detection and version bumps. See package Command.

fastskill publish

Publish packaged artifacts to blob storage with job tracking. See publish Command.

Diagnostics

fastskill version

Show CLI version.

Version Command

fastskill version

Display the FastSkill CLI version information.

fastskill version

What it shows:

CLI version number (e.g., fastskill 0.9.3)
Based on the version defined in Cargo.toml

Use cases:

Verify FastSkill installation
Check version for compatibility
Include in bug reports

Example output:

$ fastskill version
fastskill 0.9.3

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

​Overview

​Installation

​Basic Usage

​Get Help

​Global Options

​Command Categories

​Workspace & lifecycle

fastskill init

fastskill install

fastskill update

fastskill reindex

fastskill serve

​Skills

fastskill add

fastskill read

fastskill list

fastskill disable

fastskill remove

fastskill show

​Registry & search

fastskill search

fastskill sources

fastskill auth

​Packaging & publish

fastskill package

fastskill publish

​Diagnostics

fastskill version

​Version Command

​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

Version Command

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