Example Usage

Execute with npx Node.js package manager quick package executable and copy over from a source user or organization repository to the local directory

npx gh-cp user/repo/.github/workflows .

Note: you can also execute with pnpm via: pnpm dlx gh-cp

Install

Install globally with pnpm or with npm:

# install with pnpm globally
pnpm add -g gh-cp

# or install with npm globally
npm install -g gh-cp

Requirements: Node.js 24+. Optional but recommended: GitHub CLI (gh) and/or git on your PATH for auth and fewer HTTPS rate limits.

Usage

# Copy a repo subtree into the current directory (like cp -r repo/.devcontainer .)
npx gh-cp lirantal/npq/.devcontainer .

# Explicit destination and branch
npx gh-cp cli/cli --path ./upstream --ref trunk

# Preview and machine-readable summary
npx gh-cp cli/cli/README.md --dry-run --verbose
npx gh-cp cli/cli/README.md --json .

On success, gh-cp prints a short stdout summary (for example ✔︎ copied …) unless you pass --json (then only JSON is printed). Errors go to stderr with the version and a clear reason when the repo path or ref is wrong. See CLI output & errors.

Flags

| Flag | Description | |------|-------------| | -h, --help | Usage | | -V, --version | Version | | -v, --verbose | Log strategy and progress to stderr | | --path DIR | Output directory (overrides optional second positional) | | --ref REF | Branch, tag, or SHA (overrides #ref in the source spec) | | -f, --force | Overwrite existing files | | --dry-run | Show planned writes without writing | | --json | Print JSON summary on success (no human success line on stdout) |

Source syntax: owner/repo[/path][#ref] (also supports GitHub web path forms like owner/repo/blob/ref/path). Details: docs/features/source-spec.md.

Documentation

• docs/README.md — overview and feature index
• CLI output & errors — success line, stderr errors, exit codes
• Authentication & strategies — gh → git → HTTPS order

Contributing

Please consult CONTRIBUTING for guidelines on contributing to this project.

Author

gh-cp © Liran Tal, Released under the Apache-2.0 License.