OrcAI.Tool 0.3.0

OrcAI CLI

A CLI tool for automating bulk GitHub repository upgrades. It reads a YAML job configuration file and manages GitHub Projects, issues, and Copilot assignments across multiple repositories.

Prerequisites

• gh CLI: Install from cli.github.com — must be installed and on PATH
• Authentication: One of the following must be configured before running any command other than orcai auth:
  1. Stored PAT — ORCAI_PAT env var, or ~/.config/orcai/auth.json with "type": "pat"
  2. Stored GitHub App — ORCAI_APP_ID / ORCAI_APP_INSTALLATION_ID / ORCAI_APP_KEY_PATH / ORCAI_APP_PRIVATE_KEY env vars, or ~/.config/orcai/auth.json with "type": "app"
  3. GH_TOKEN environment variable
  4. Ambient gh CLI auth (gh auth token)

Usage

YAML Config Format

All data commands require a YAML file:

job:
  title: "My Project Title"
  org:   "my-github-org"
  # skipCopilot: true  # optional — disable @copilot assignment

repos:
  - "repo-one"
  - "repo-two"

issue:
  template: "./issue-body.md"
  labels: ["migration", "automated"]

generate

Scaffold a new YAML job config and a stub Markdown issue template.

orcai generate --name <name> --org <org> [--repo <repo>...] [--output <path>] [--skip-copilot] [--interactive]

Outputs a <slug>.yml config file and a <slug>.md stub issue template.

auth

Store credentials for use by all other commands. Three subcommands are available: pat, app, and create-app.

PAT:

orcai auth pat --token <token>

GitHub App:

orcai auth app --app-id <id> --key <path> --installation-id <id>

Create GitHub App (browser-based):

orcai auth create-app [--app-name <name>] [--org <org>] [--port <port>]

This command automates app registration but app installation requires a manual step:

1. Automatic — opens your browser, submits the app manifest to GitHub, exchanges the OAuth code for credentials, saves the private key to ~/.config/orcai/app.pem and writes auth.json. A second browser tab opens to the app's permissions page so you can grant the org-level Projects: Read and write permission (not settable via manifest).
2. Manual — you must install the app on your org or account by clicking through the GitHub UI. The CLI prints step-by-step instructions showing exactly where to find the installation ID in the GitHub UI.
3. Automatic (interactive) — if running in a terminal, you are shown the install instructions and then prompted to enter the installation ID immediately, which completes the auth.json configuration. In non-interactive (CI) mode, the same instructions plus the manual command to run are printed instead:

  orcai auth app --app-id <id> --key <path> --installation-id <id>

Credentials are stored in ~/.config/orcai/auth.json and validated immediately. Environment variables (ORCAI_PAT, ORCAI_APP_ID, etc.) override stored values at runtime without modifying the file.

See docs/app-auth.md for setting up GitHub App authentication and docs/AUTH-ENV-VARS.md for environment variable reference.

run

Execute a bulk upgrade job. For each repository in the YAML, orcai will:

1. Find or create the GitHub Project for the org (idempotent)
2. Find or create an issue using the issue template (idempotent)
3. Add the issue to the GitHub Project (idempotent)
4. Assign @copilot to the issue if no assignees are set

orcai run <yaml_file> [--verbose] [--auto-create-labels] [--skip-copilot]

On success a lock file (<basename>.lock.json) is written alongside the YAML. On subsequent runs, if the YAML is unchanged the lock file is used to short-circuit all network calls.

info

Display a formatted snapshot of the current state of a job.

orcai info <yaml_file> [--skip-lock] [--save-lock]

By default, reads from the lock file if it exists (no network calls). Use --skip-lock --save-lock to force a fresh fetch and update the lock file.

cleanup

Tear down everything that run created for the same YAML configuration.

orcai cleanup <yaml_file> [--dryrun]

Closes open PRs linked to each issue, deletes each issue, deletes the GitHub Project, and removes the lock file.

For full flag details, output formats, lock file schema, and advanced usage see docs/cli-reference.md.

OrcAI Nushell Scripts

This repository contains Nushell scripts for managing GitHub projects and issues in bulk.

Prerequisites

• Nushell: Install Nushell from nushell.sh
• GitHub CLI: Install the GitHub CLI from cli.github.com

Authentication

Local Environment

Run gh auth login to authenticate with GitHub CLI.

CI Environment

Set the GH_TOKEN environment variable with a GitHub Personal Access Token that has the necessary permissions (project and issue management).

Scripts

orca.nu

Creates a GitHub project and adds issues to it across multiple repositories.

Usage:

./orca.nu [--verbose] <yaml_file>

Options:

• --verbose: Enable verbose output
• yaml_file: Path to YAML configuration file

YAML Configuration Structure:

job:
  title: "Project Title"
  org: "organization-name"
repos:
  - "repo1"
  - "repo2"
issue:
  template: "path/to/issue-template.md"
  labels:
    - "label1"
    - "label2"

cleanup.nu

Deletes a GitHub project and cleans up associated issues and PRs.

Usage:

./cleanup.nu [--dryrun] <yaml_file>

Options:

• --dryrun: Preview what would be deleted without actually deleting
• yaml_file: Path to YAML configuration file

YAML Configuration Structure:

job:
  title: "Project Title"
  org: "organization-name"