> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gofastskill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# repos Command

> Manage skill repositories and browse the remote catalog with fastskill repos.

# repos Command

Manage skill repositories and browse remote skill catalog.

<Info>
  The `repos` command is the primary interface for repository management and catalog browsing in FastSkill. Use `fastskill search` for semantic search of installed skills.
</Info>

## Usage

```bash theme={null}
fastskill repos <SUBCOMMAND>
```

## Subcommands

### list

List all configured repositories.

```bash theme={null}
# List repositories in table format
fastskill repos list

# List in JSON format
fastskill repos list --json
```

**Output Format**:

* Default: Human-readable table with name, type, URL/path, priority
* JSON: Machine-readable array with full repository details

**Example Output**:

```
Name             Type              URL/Path                     Priority
---------------- ---------------- ---------------------------- ---------
public-registry  http-registry    https://api.fastskill.io    0
team-skills      git-marketplace  https://github.com/team/skills.git 1
local-dev        local             ./skills                    2
```

### add

Add a new repository to your skill sources.

```bash theme={null}
# Add HTTP registry
fastskill repos add public --repo-type http-registry https://api.fastskill.io --priority 0

# Add Git marketplace
fastskill repos add team-skills --repo-type git-marketplace https://github.com/team/skills.git --priority 1

# Add ZIP URL source
fastskill repos add custom --repo-type zip-url https://cdn.example.com/skills/ --priority 2

# Add local directory
fastskill repos add local-dev --repo-type local ./skills --priority 3

# Add with authentication (PAT)
fastskill repos add private-repo --repo-type git-marketplace https://github.com/team/private.git \
  --auth-type pat --auth-env GITHUB_TOKEN

# Add with SSH key
fastskill repos add private-repo --repo-type git-marketplace https://github.com/team/private.git \
  --auth-type ssh-key --auth-key-path ~/.ssh/id_rsa

# Add with basic auth
fastskill repos add registry --repo-type http-registry https://api.example.com \
  --auth-type basic --auth-username admin --auth-env REGISTRY_PASSWORD

# Add with API key
fastskill repos add registry --repo-type http-registry https://api.example.com \
  --auth-type api_key --auth-env API_KEY
```

**Options**:

| Flag              | Short | Type   | Default  | Description                                                                                      |
| ----------------- | ----- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `--repo-type`     | -     | string | required | Repository type: `git-marketplace`, `http-registry`, `zip-url`, or `local`                       |
| `--priority`      | -     | number | 0        | Lower number = higher priority (used for conflict resolution)                                    |
| `--branch`        | -     | string | none     | Git branch to checkout (for git-marketplace)                                                     |
| `--tag`           | -     | string | none     | Git tag to checkout (for git-marketplace)                                                        |
| `--auth-type`     | -     | string | none     | Authentication type: `pat`, `ssh-key`, `ssh`, `basic`, or `api_key` (use underscore, not hyphen) |
| `--auth-env`      | -     | string | none     | Environment variable for PAT, password, or API key                                               |
| `--auth-key-path` | -     | path   | none     | SSH key path for ssh-key or ssh auth                                                             |
| `--auth-username` | -     | string | none     | Username for basic auth                                                                          |

**Repository Types**:

1. **git-marketplace**: Git repository with `marketplace.json` for skill discovery
   * Supports PAT, SSH Key, SSH, Basic Auth
   * Can specify branch or tag
   * Scans for skills across repository structure

2. **http-registry**: HTTP-based registry with flat skill index
   * Supports Basic Auth, API Key
   * Fast skill lookup via API
   * Best for production registries

3. **zip-url**: Base URL for ZIP file downloads
   * Supports PAT, Basic Auth
   * Downloads skills from `{base_url}/{skill-id}-{version}.zip`

4. **local**: Local filesystem path
   * No authentication needed
   * Best for development workflows

**Priority-Based Conflict Resolution**:

* When multiple sources provide the same skill ID, the source with lower priority number wins
* Priority 0 is highest
* Example: If `public-registry` (priority 0) and `team-skills` (priority 1) both have `pptx`, `public-registry`'s version is used

### remove

Remove a repository from your sources.

```bash theme={null}
# Remove a repository
fastskill repos remove team-skills

# Remove multiple repositories
fastskill repos remove team-skills local-dev
```

**Behavior**:

* Removes repository from configuration file
* Does not uninstall skills that were installed from this repository
* Skills remain in skills directory until explicitly removed

### info

Display detailed information about a specific repository.

```bash theme={null}
# Show repository details
fastskill repos info public-registry

# Show in JSON format
fastskill repos info team-skills --json
```

**Example Output**:

```
Name: team-skills
Type: git-marketplace
URL: https://github.com/team/skills.git
Branch: main
Priority: 1
Auth: pat (GITHUB_TOKEN)
```

### update

Update repository metadata.

```bash theme={null}
# Update branch
fastskill repos update team-skills --branch develop

# Update priority
fastskill repos update public-registry --priority 0

# Update both
fastskill repos update team-skills --branch main --priority 2
```

**Options**:

| Flag         | Short | Type   | Default | Description                                 |
| ------------ | ----- | ------ | ------- | ------------------------------------------- |
| `--branch`   | -     | string | none    | New branch for git-marketplace repositories |
| `--priority` | -     | number | none    | New priority value                          |

### test

Test repository connectivity and accessibility.

```bash theme={null}
# Test a repository
fastskill repos test public-registry

# Test git marketplace
fastskill repos test team-skills
```

**What it tests**:

* HTTP registries: Connectivity to API endpoint
* Git marketplaces: Clone/access to repository
* ZIP URLs: Accessibility of base URL
* Local: Directory exists and is readable

**Exit codes**:

* 0: Repository is accessible
* 1: Cannot connect or access repository
* 2: Invalid configuration

### refresh

Refresh repository cache (re-fetch from source).

```bash theme={null}
# Refresh specific repository
fastskill repos refresh team-skills

# Refresh all repositories
fastskill repos refresh
```

**When to use**:

* After repository has been updated with new skills
* To get latest skill versions
* If cache is stale or corrupted

**What it does**:

* Re-fetches repository metadata
* Updates local cache
* Invalidates stale skill information

### skills

List skills in repository catalog.

```bash theme={null}
# List all skills from default repository (table format, default)
fastskill repos skills

# Filter by scope
fastskill repos skills --scope acme

# List all versions
fastskill repos skills --all-versions

# Include pre-release versions
fastskill repos skills --include-pre-release

# JSON output
fastskill repos skills --json

# Grid format
fastskill repos skills --format grid

# Combined options
fastskill repos skills --scope acme --all-versions --json
```

**Options**:

* `--scope <SCOPE>`: Filter skills by scope (exact match)
* `--all-versions`: Include all versions for each skill (default: latest only)
* `--include-pre-release`: Include pre-release versions (default: exclude)
* `--format <table|json|grid>`: Output format (default: table)
* `--json`: Shorthand for --format json (mutually exclusive with --format)
* `--repository <NAME>`: Repository name to list skills from (defaults to default repository if not specified)

**Output Format**:

* **Grid (default)**: Human-readable table with columns: scope, name, description (truncated to 50 chars), latest version (or "version" when `--all-versions` is used), published date
* **JSON**: Machine-readable array with fields: id, scope, name, description, latest\_version, published\_at, and optionally versions array

### show

Display detailed information about a specific skill from the catalog.

```bash theme={null}
# Show skill details by ID
fastskill repos show <skill-id>

# Show skill from specific repository
fastskill repos show <skill-id> --repository my-repo
```

**Parameters**:

* `<skill-id>`: Full skill identifier (e.g., `acme/web-scraper`)
* `--repository <NAME>`: Repository to search (defaults to default repository)

**Output Format**:
Displays comprehensive skill information including:

* Skill metadata (name, description, author, version)
* Capabilities and tags
* Installation instructions
* Dependencies and requirements
* Documentation links
* Change log and release notes

**Example Output**:

```
Skill: acme/web-scraper
Version: 2.0.0
Description: A web scraping skill for extracting data from websites
Author: ACME Corp
Tags: web, scraping, data-extraction
Capabilities: scrape_website, extract_data, handle_cookies

Repository: my-registry
Published: 2025-01-15T10:30:00Z
Updated: 2025-01-20T14:00:00Z

Installation: fastskill add acme/web-scraper
Homepage: https://github.com/acme/web-scraper
Documentation: https://docs.acme.com/web-scraper

Requirements:
- Node.js 16+
- Internet access
- User agent headers configured
```

### versions

List all available versions for a specific skill.

```bash theme={null}
# List versions for a skill
fastskill repos versions <skill-id>

# List versions from specific repository
fastskill repos versions <skill-id> --repository my-repo
```

**Parameters**:

* `<skill-id>`: Full skill identifier (e.g., `acme/web-scraper`)
* `--repository <NAME>`: Repository to query (defaults to default repository)

**Output Format**:
Displays a table of versions with:

* Version number
* Release date
* Release notes (if available)
* Pre-release status
* Compatibility information

**Example Output**:

```
Versions for skill: acme/web-scraper

+---------+---------------------+-------------+-------------+
| Version | Published At        | Pre-release | Notes      |
+---------+---------------------+-------------+-------------+
| 2.0.0   | 2025-01-15T10:30:00Z | false       | Major update |
| 1.5.2   | 2025-01-10T08:15:00Z | false       | Bug fixes   |
| 1.5.1   | 2025-01-05T16:45:00Z | false       | Performance |
| 1.5.0   | 2024-12-20T12:00:00Z | false       | New features|
| 1.4.0   | 2024-11-15T09:30:00Z | false       | API changes |
+---------+---------------------+-------------+-------------+
```

## Configuration File Location

Repositories are stored in `skill-project.toml` at project root:

```toml skill-project.toml theme={null}
[tool.fastskill.repositories]

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

[[tool.fastskill.repositories]]
name = "team-skills"
type = "git-marketplace"
url = "https://github.com/team/skills.git"
branch = "main"
priority = 1

# Authentication is usually configured via CLI flags (--auth-type, --auth-env)
# or your registry provider docs; avoid duplicating secrets in committed files.
```

## Authentication Types

### PAT (Personal Access Token)

* Use for Git repositories and private registries
  * Token stored in environment variable
  * Example:
    ```bash theme={null}
    fastskill repos add private-repo --repo-type git-marketplace https://github.com/team/repo.git \
      --auth-type pat --auth-env GITHUB_TOKEN
    ```
  ```bash theme={null}
  export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
  ```

### SSH Key

* Use for Git repositories with SSH access
  * Key path points to private key file
  * Example:
    ```bash theme={null}
    fastskill repos add private-repo --repo-type git-marketplace git@github.com:team/repo.git \
      --auth-type ssh-key --auth-key-path ~/.ssh/id_rsa
    ```

### SSH

* Use for Git repositories with SSH protocol
  * Similar to SSH Key but may use system SSH agent
  * Example:
    ```bash theme={null}
    fastskill repos add private-repo --repo-type git-marketplace git@github.com:team/repo.git \
      --auth-type ssh --auth-key-path ~/.ssh/id_rsa
    ```

### Basic Auth

* Use for HTTP registries with username/password
  * Password stored in environment variable
  * Example:
    ```bash theme={null}
    fastskill repos add registry --repo-type http-registry https://api.example.com \
      --auth-type basic --auth-username admin --auth-env REGISTRY_PASSWORD
    ```

### API Key

* Use for HTTP registries with API key authentication
  * API key stored in environment variable
  * Example:
    ```bash theme={null}
    fastskill repos add registry --repo-type http-registry https://api.example.com \
      --auth-type api_key --auth-env API_KEY
    ```

## Multi-Source Skill Resolution

FastSkill supports multiple sources with priority-based resolution:

```bash theme={null}
# Add multiple sources
fastskill repos add public-registry --repo-type http-registry https://api.fastskill.io --priority 0
fastskill repos add team-skills --repo-type git-marketplace https://github.com/team/skills.git --priority 1
fastskill repos add local-dev --repo-type local ./skills --priority 2
```

**Resolution process**:

1. Repositories are consulted in ascending priority order (0 before 1 before 2).
2. The first repository that satisfies the lookup wins for that skill id.
3. Lower numeric priority means earlier in that order (0 is tried before 10).

**Example**:

* `public-registry` (priority 0): `pptx v1.0.0`
* `team-skills` (priority 1): `pptx v1.2.0`
* Result: `pptx v1.0.0` from `public-registry` is used because priority 0 is consulted first.

## Examples

### Setting up a development environment

```bash theme={null}
# Add public registry
fastskill repos add public --repo-type http-registry https://api.fastskill.io --priority 0

# Add team repository
fastskill repos add team --repo-type git-marketplace https://github.com/team/skills.git \
  --auth-type pat --auth-env GITHUB_TOKEN --priority 1

# Add local development directory
fastskill repos add local-dev --repo-type local ./skills --priority 2
```

### Creating a Git marketplace

```bash theme={null}
# 1. Create a directory for your marketplace
mkdir my-marketplace
cd my-marketplace

# 2. Add skills (each in its own subdirectory)
git clone https://github.com/org/pptx.git skills/pptx
git clone https://github.com/org/web-scraper.git skills/web-scraper

# 3. Create marketplace.json
fastskill marketplace create \
  --name "My Marketplace" \
  --owner-name "Your Name" \
  --description "Collection of skills" \
  --base-url https://cdn.example.com/marketplace/

# 4. Commit and push
git init
git add .
git commit -m "Initial marketplace"
git remote add origin https://github.com/username/marketplace.git
git push -u origin main
```

### Troubleshooting

<AccordionGroup>
  <Accordion title="Repository not found">
    <Warning>
      **Check name**: Ensure the repository name matches what you added.

      ```bash theme={null}
      fastskill repos list
      ```
    </Warning>
  </Accordion>

  <Accordion title="Authentication failed">
    <Warning>
      **Verify credentials**:

      ```bash theme={null}
      # Check environment variable
      echo $GITHUB_TOKEN

      # Test SSH key
      ssh -T git@github.com

      # Test basic auth credentials
      curl -u username:password https://api.example.com/health
      ```
    </Warning>
  </Accordion>

  <Accordion title="Priority not working">
    <Tip>
      **Verify priority values**: Lower numbers have higher priority.

      ```bash theme={null}
      fastskill repos list
      ```

      Priority 0 is highest, priority 10 is lower.
    </Tip>
  </Accordion>
</AccordionGroup>

<Note>
  Repositories configuration is stored in `skill-project.toml` and should be committed to version control. Authentication credentials (environment variables) should never be committed.
</Note>

## See Also

* [Search Command](/cli-reference/search-command) - Semantic search for installed skills
* [Install Command](/cli-reference/skill-commands#fastskill-install) - Installing skills from repositories
* [Init Command](/cli-reference/skill-commands#fastskill-init) - Creating skill-project.toml