CLI Reference Overview

Overview

The FastSkill CLI is how you install and operate skills: manifests and skills.lock, validation and fastskill eval, search, plus serve when you want a local HTTP surface.

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

Installation

Use the same install method as the Installation guide (release binary recommended). After install, confirm the CLI is on your PATH:

fastskill -V

For Git-based skill sources, use a build that includes Git support if your distribution splits binaries that way. See Installation for details.

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
`-V, --version`	Print the `fastskill` binary version and exit	`fastskill -V`
`--verbose`, `-v`	Enable verbose logging	`fastskill -v list`
`--repositories-path`	Override path to `repositories.toml`	`fastskill --repositories-path ./repositories.toml list`
`--global`	Use the user-level global skills directory	`fastskill --global list`
Positional `SKILL_ID`	Shorthand for `fastskill read <id>` when no subcommand is given	`fastskill pptx`
`--help`, `-h`	Help	`fastskill --help`

Command Categories

Project and 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 (--host, --port). Web UI and API routes are served with the process. See serve Command.

Skills

fastskill add

Add skills from registry ID, git, zip, or local folder (supports -r for recursive folder add, --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 --format table|json|grid|xml, --json). See skill commands.

fastskill remove

Remove skills by ID. See skill commands.

Registry & search

fastskill search

Search remote catalogs by default; use --local for embedding search on installed skills. See search Command.

fastskill repos

Manage repositories (list/add/remove/info/update/test/refresh) and browse remote skill catalog with authentication and priority. See repos Command.

Diagnostics and tooling

fastskill version

Show CLI version.

fastskill eval

Validate and run skill evaluation suites. See eval Command.

fastskill analyze

Similarity matrix, clusters, duplicates. See tooling commands.

fastskill doctor

Check environment readiness (skills directory, embedding provider, auth). See tooling commands.

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 opt-in registry publishing builds, see the platform-managed deploy workflow. Skill distribution is handled by the platform operator rather than a self-hosted CLI publish path.

Environment Variables

Scripting and automation

Use the CLI in scripts the same way you would run git or uv: non-interactive flags (--yes, --force, --json) are preferred for automation.

Batch operations

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

# Alternative: use recursive add for all skills under a directory
fastskill add ./skills -r -e --group dev

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

Example: local project

# 1. Add a skill you are iterating on (optional group)
fastskill add ./skills/my-skill -e --group dev

# 2. Apply the manifest and refresh the local index
fastskill install
fastskill reindex

# 3. Browse with the bundled web UI
fastskill serve --port 8080

# 4. Try search (remote catalog by default; add --local for installed skills)
fastskill search "text processing"

Example: reproducible install

fastskill install --lock
fastskill reindex
fastskill serve --port 8080

For running fastskill in automation (build machines, sandboxes), install the CLI in the job image, check out your repo, then run the same commands with secrets injected for registry tokens and OPENAI_API_KEY when needed.

Troubleshooting

Common Issues

Command Not Found

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

which fastskill
fastskill -V

Permission Errors

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

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

Service permissions: 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

More verbose output

fastskill -v install

Some distributions document extra logging variables; check your install notes if you need trace-level diagnostics.

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.

Use groups for optional skills

Use groups (for example --group dev) and install with --without dev when you want a smaller production skill set.

Check the server when you use serve

Confirm http://<host>:<port>/ responds after upgrades or config changes.

Back up manifests before big changes

Keep copies of skill-project.toml, skills.lock, and any custom .fastskill config before bulk edits.

Commands can change installed skills and manifest files. Try changes on a copy of the project or a branch first if you are unsure.

​Overview

​Installation

​Basic Usage

​Get Help

​Global Options

​Command Categories

​Project and lifecycle

fastskill init

fastskill install

fastskill update

fastskill reindex

fastskill serve

​Skills

fastskill add

fastskill read

fastskill list

fastskill remove

​Registry & search

fastskill search

fastskill repos

​Diagnostics and tooling

fastskill version

fastskill eval

fastskill analyze

fastskill doctor

​Version Command

​fastskill version

​Configuration

​Configuration Files

​Environment Variables

​Scripting and automation

​Batch operations

​JSON Output

​Exit Codes

​Examples

​Example: local project

​Example: reproducible install

​Troubleshooting

​Common Issues

​More verbose output

​Best Practices

Overview

Installation

Basic Usage

Get Help

Global Options

Command Categories

Project and lifecycle

Skills

Registry & search

Diagnostics and tooling

Version Command

fastskill version

Configuration

Configuration Files

Environment Variables

Scripting and automation

Batch operations

JSON Output

Exit Codes

Examples

Example: local project

Example: reproducible install

Troubleshooting

Common Issues

More verbose output

Best Practices