gh-cp
Copy files or directories from a GitHub repository path into a local folder — no full clone, no git history.
## 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
```sh
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`:
```sh
# 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](https://cli.github.com/) (`gh`) and/or `git` on your `PATH` for auth and fewer HTTPS rate limits.
## Usage
```sh
# 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 .
# Save a reusable source and install from it later
npx gh-cp alias devcontainer github.com/lirantal/create-node-lib/tree/main/template/.devcontainer/
npx gh-cp alias list
npx gh-cp install devcontainer .
npx gh-cp install
```
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](./docs/features/cli-output-and-errors.md).
### 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 output for copy summaries and alias listings |
Source syntax: `owner/repo[/path][#ref]` (also supports GitHub web path forms like `owner/repo/blob/ref/path`). Details: [docs/features/source-spec.md](./docs/features/source-spec.md).
### Aliases and install
Save frequently used sources as aliases:
```sh
npx gh-cp alias devcontainer github.com/lirantal/create-node-lib/tree/main/template/.devcontainer/
```
List saved aliases:
```sh
npx gh-cp alias list
```
Install directly from an alias:
```sh
npx gh-cp install devcontainer .
```
Run `npx gh-cp install` without an alias name to choose from saved aliases in a built-in interactive menu. The menu uses Node.js TTY APIs, so it only runs in an interactive terminal; pass an alias name when scripting or using `--json`. See [Aliases and install](./docs/features/aliases-and-install.md).
## Documentation
- [docs/README.md](./docs/README.md) — overview and feature index
- [Aliases and install](./docs/features/aliases-and-install.md) — save reusable sources and choose them interactively
- [CLI output & errors](./docs/features/cli-output-and-errors.md) — success line, stderr errors, exit codes
- [Authentication & strategies](./docs/features/authentication-and-strategies.md) — `gh` → `git` → HTTPS order
## Contributing
Please consult [CONTRIBUTING](./CONTRIBUTING.md) for guidelines on contributing to this project.
## Author
**gh-cp** © [Liran Tal](https://github.com/lirantal), Released under the [Apache-2.0](./LICENSE) License.