Skip to main content

Discovering Remote Repositories

SCM can search GitHub and GitLab to find repositories containing bundles and profiles you can use.

Quick Start​

# Find all public SCM repositories
scm remote discover

# Search with a keyword
scm remote discover golang

# Filter by minimum stars
scm remote discover --stars 10

How Discovery Works​

SCM searches for repositories named scm or starting with scm- on GitHub and GitLab. It validates that discovered repositories have the proper scm/v1/ structure before showing them.

Search Sources​

# Search both GitHub and GitLab (default)
scm remote discover

# GitHub only
scm remote discover --source github

# GitLab only
scm remote discover --source gitlab

Filtering Results​

# Keyword search (matches description and topics)
scm remote discover python

# Minimum star count
scm remote discover --stars 5

# Limit results per source
scm remote discover --limit 10

# Combine filters
scm remote discover security --source github --stars 10 --limit 20

Command Reference​

scm remote discover [query] [flags]

Flags​

FlagShortDefaultDescription
--source-sallSearch source: github, gitlab, or all
--stars0Minimum star count filter
--limit-n30Maximum results per source

Interactive Workflow​

When you run scm remote discover, the results are displayed in a table:

Searching repositories... found 5

  # │ Forge  │ Repository          │ Stars │ Description
────┼────────┼─────────────────────┼───────┼─────────────────────────────────────
  1 │ GitHub │ alice/scm-golang    │   142 │ Go development context bundles
  2 │ GitHub │ corp/scm-security   │    89 │ Security-focused prompts and...
  3 │ GitLab │ team/scm-internal   │    34 │ Internal development standards
  4 │ GitHub │ bob/scm-python      │    28 │ Python tooling fragments
  5 │ GitHub │ dev/scm-testing     │    15 │ Testing patterns and practices

Add remote? Enter number (or 'q' to quit):

Enter a number to add that repository as a remote:

Add remote? Enter number (or 'q' to quit): 1
Name for remote [alice]: golang-bundles
Added remote 'golang-bundles' → https://github.com/alice/scm-golang

After Adding a Remote​

Once you've added a remote, you can:

Browse Its Contents​

scm remote browse golang-bundles

Pull Bundles Locally​

# Preview before pulling
scm remote pull golang-bundles/go-testing --type bundle

# Pull without preview
scm fragment install --blind golang-bundles/go-testing

Use Content Directly​

Reference remote content without pulling:

# Use a remote profile
scm run -p golang-bundles/go-developer "help me"

# Use a remote fragment
scm run -f golang-bundles/testing#fragments/table-driven "write tests"

Reference in Profiles​

# .scm/profiles/my-profile.yaml
description: My Go development profile
parents:
  - golang-bundles/go-developer
bundles:
  - my-local-additions

Authentication​

For private repositories or to avoid rate limits, set authentication tokens:

# GitHub
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# GitLab
export GITLAB_TOKEN=glpat-xxxxxxxxxxxx

MCP Server Integration​

The discovery feature is also available as an MCP tool:

{
  "tool": "discover_remotes",
  "arguments": {
    "query": "python",
    "source": "github",
    "min_stars": 5
  }
}

This enables AI assistants to help you find and add relevant bundles during your workflow.

Tips​

Finding Quality Repositories​

  • Use --stars to filter for popular, well-maintained repos
  • Check the description for relevance to your needs
  • Browse the repo contents before pulling everything

Naming Remotes​

Choose descriptive names that indicate the content type:

  • security for security-focused bundles
  • team-standards for your organization's standards
  • python-tools for language-specific tooling

Staying Updated​

After adding remotes, keep them in sync:

# Sync all remote dependencies
scm remote sync

# Update specific remote
scm remote update golang-bundles

Creating Discoverable Repositories​

Want your bundles to be discoverable? See the Sharing Bundles guide for how to structure and publish your own SCM repository.