nomos-cli

GitHub Copilot Assets installer - A CLI tool to install and manage GitHub Copilot assets.

Installation

npm install -g @jhidalgo3/nomos-cli

Usage

Initialize project

From command line

Install one or more repositories directly:

# Full HTTPS format
nomos-cli init https://github.com/user/repo

# SSH format
nomos-cli init [email protected]:user/repo

# Short format (assumes github.com)
nomos-cli init user/repo

# With specific branch (automatically does shallow clone)
nomos-cli init https://github.com/user/repo@develop
nomos-cli init user/repo@main
nomos-cli init [email protected]:user/repo@feature-branch

# Multiple repositories
nomos-cli init https://github.com/repo1 [email protected]:repo2 user/repo3@develop

Repositories are automatically saved to .github/copilots.yaml.

From configuration file

If you run nomos-cli init without arguments, it will read repositories from .github/copilots.yaml:

nomos-cli init

Configuration file .github/copilots.yaml

dependencies:
  github-copilot:
    # Simple format - uses default patterns
    - https://github.com/user/repo1
    - [email protected]:user/repo2
    - user/repo3  # Short format
    
    # With specific branch (does shallow clone with --depth 1)
    - https://github.com/user/repo4@develop
    - user/repo5@main
    
    # Extended format - with custom patterns
    - repo: https://github.com/user/repo6
      patterns:
        - .github/agent/**
        - .github/workflows/**/*.yml

# Future support for other copilots:
# claude:
# gemini:
# cursor:

See complete example at docs/copilots.yaml.example.

Branch Syntax (@branch)

nomos-cli supports the @branch syntax for cloning specific branches. When using this syntax, a shallow clone (--depth 1) is automatically performed to optimize speed and disk space.

# Clone a specific branch
nomos-cli init user/repo@develop

# Works with all formats
nomos-cli init https://github.com/user/repo@main
nomos-cli init [email protected]:user/repo@feature-branch

See complete guide at docs/BRANCH_SYNTAX.md.

Multi-Repository Complete Guide

For a detailed guide on how to manage multiple repositories, see docs/MULTI_REPO_GUIDE.md.

Additional options

With dry-run mode (keeps temporary directory for inspection):

nomos-cli --dry init user/repo

Update configuration

Compare and update local files with versions from all repositories in .github/copilots.yaml:

nomos-cli update

The update command:

• Processes all repositories defined in .github/copilots.yaml
• Compares local files with remote versions
• Shows a summary of all changes (modified, added, deleted)
• Asks for confirmation before applying changes
• Automatically overwrites modified files, adds new files, and removes deleted files

Configuration with Glob Patterns

The tool supports advanced glob patterns to specify which files to copy from the repository.

Note: Currently only supports github-copilot. Future support for claude, gemini, cursor and other code assistants is planned.

Pattern Examples

// In source code (bin/nomos-cli.js)
const REPO_DIR_COPILOTS = [
  ".github/agent/**",           // Everything from .github/agent/
  ".github/workflows/**/*.yml", // Only YAML workflows
  "docs/**/*.md"                // Only markdown files from docs
];

Supported Patterns

| Pattern | Description | Example | |---------|-------------|---------|

".github/agent"  // Copies entire directory (equivalent to ".github/agent/**")

For more examples, see docs/GLOB_EXAMPLES.md.

Commands

init [repos...]

Initialize the project by installing repositories.

# From arguments
nomos-cli init https://github.com/user/repo

# From copilots.yaml
nomos-cli init

# Multiple repos
nomos-cli init user/repo1 user/repo2

Formatos soportados:

• HTTPS: https://github.com/user/repo
• SSH: [email protected]:user/repo
• Abreviado: user/repo (asume github.com)

Opciones:

• --dry: Modo dry-run, mantiene el directorio temporal para inspección

update

Update configuration by comparing with all repositories in .github/copilots.yaml.

nomos-cli update

# Auto-approve all changes without confirmation
nomos-cli update -y
# or
nomos-cli update --yes

The command:

1. Reads all repositories from .github/copilots.yaml
2. Clones each repository to a temporary directory
3. Compares local files with remote ones
4. Shows a summary of changes (modified, added, deleted)
5. Asks for confirmation before applying changes
6. Overwrites all modified files
7. Adds all new files
8. Removes all deleted files

Options:

• -y, --yes: Auto-approve all changes without confirmation

Requirements

• Node.js >= 16
• Git installed and configured with access to repositories

Development

# Clonar el repositorio
git clone https://github.com/jhidalgo3/nomos-cli.git

# Instalar dependencias
npm install

# Ejecutar localmente
node bin/nomos-cli.js init

# Ejecutar tests
npm test

# Ejecutar linter
npm run lint
npm run lint:fix  # Auto-fix

CI/CD

El proyecto usa GitHub Actions para CI/CD:

• Tests y Seguridad: Se ejecuta en todos los PRs y pushes a develop

  • Linting con ESLint
  • Tests en Node 18 y 20
  • Auditoría de seguridad (falla en vulnerabilidades HIGH y CRITICAL)

• Publicación a NPM: Se ejecuta al crear tags desde main

  git tag v1.0.1
  git push origin v1.0.1

Ver docs/PUBLISHING.md para detalles completos sobre publicación.

Licencia

ISC

Autor

Jose Maria Hidalgo Garcia