# CLI reference

This page lists every option exposed by `gophercram`. For grouped
walkthroughs see the [usage guide](usage.md), and for ready-made workflows
see the [recipes](recipes.md).

```
gophercram [subcommand] [options] [path ...]
```

If no positional path is given, GopherCram packs the current directory.

## Subcommands

| Name | Purpose |
|---|---|
| (default) / `pack` | Pack the given path(s) into a single document. |
| `extract <input> <dest>` | Reverse-pack: reconstruct the file tree from an existing GopherCram output. |
| `mcp` | Run an MCP (Model Context Protocol) server over stdio. |
| `watch` | Poll the working tree and repack on changes. |
| `issues` | Fetch open GitHub issues / PRs for an owner/repo and print them. |

## Logging

| Flag | Effect |
|---|---|
| `--verbose` | Print detailed progress; walker prints every skipped path. |
| `--quiet` | Suppress non-error console output. |
| `--stdout` | Write the packed output to stdout (implies `--quiet`). |
| `--stdin` | Read file paths to include from stdin, one per line. |
| `--copy` | Copy the packed output to the system clipboard. |
| `--top-files-len N` | Number of largest files (by tokens) to show in the run report. |
| `--token-count-tree [N]` | After packing, print a flat per-file token count list; optional threshold filters small files. |

## Output

| Flag | Effect |
|---|---|
| `-o, --output FILE` | Output file path (use `-` for stdout). |
| `--style STYLE` | Output style: `xml`, `markdown`, `json`, `plain`, `skill`, or `vectors`. |
| `--path-style STYLE` | How file paths are rendered: `relative` (default), `absolute`, or `repo-relative`. |
| `--parsable-style` | Escape file content so the output remains valid XML/Markdown. |
| `--compress` | Compress code by keeping signatures and dropping bodies. Uses go/ast for Go and tree-sitter (when CGo build) for Python/JS/TS/Rust/Java; falls back to regex compressors otherwise. |
| `--output-show-line-numbers` | Prefix every line in the output with its line number. |
| `--no-file-summary` | Omit the summary section. |
| `--no-directory-structure` | Omit the directory tree. |
| `--no-files` | Omit file contents (metadata-only output). |
| `--remove-comments` | Strip comments from supported languages. |
| `--remove-empty-lines` | Drop blank lines from file content. |
| `--truncate-base64` | Replace long base64 blobs with a placeholder. |
| `--truncate-large-data` | Truncate CSV/TSV/JSONL/log files past a configurable line count. |
| `--large-data-max-lines N` | Line cap when `--truncate-large-data` is set (default 200). |
| `--header-text TEXT` | Custom text prepended to the packed output. |
| `--instruction-file-path PATH` | Path to a file whose contents are appended to the output. |
| `--split-output SIZE` | Split the output into multiple numbered files (e.g. `2mb`). |
| `--versioned-output` | If the output path exists, append `-1`, `-2`, … instead of overwriting. |
| `--include-empty-directories` | Include empty directories in the tree view. |
| `--include-full-directory-structure` | Render the full tree even when `--include` narrows the file list. |
| `--no-git-sort-by-changes` | Don't reorder files by git change frequency. |
| `--include-diffs` | Append working-tree and staged diffs to the output. |
| `--include-logs` | Append a recent git log. |
| `--include-logs-count N` | Number of commits to include when `--include-logs` is set. |
| `--include-issues N` | Fetch N open GitHub issues and embed them in the output (requires a github.com origin or `--github-owner-repo`). |
| `--include-prs N` | Fetch N open GitHub pull requests. |
| `--github-owner-repo OWNER/REPO` | Explicit owner/repo override for `--include-issues` / `--include-prs`. |

## File selection

| Flag | Effect |
|---|---|
| `--include PATTERNS` | Comma-separated glob patterns to include (repeatable). |
| `-i, --ignore PATTERNS` | Comma-separated glob patterns to ignore (repeatable). |
| `--no-gitignore` | Don't apply `.gitignore` rules. |
| `--no-dot-ignore` | Don't apply `.ignore` / `.gophercramignore` files. |
| `--no-default-patterns` | Don't apply the built-in default ignore patterns. |
| `--max-file-size N` | Skip files larger than N bytes (default 52428800). |
| `--max-files N` | Cap the total number of files included (0 = unlimited). |
| `--max-total-bytes N` | Cap the aggregate size of selected files in bytes (0 = unlimited). |
| `--follow-symlinks` | Descend into symlinked directories (off by default). |
| `--stream-threshold N` | File size (bytes) above which streaming reads kick in (default 1 MiB). |

## Remote repositories

| Flag | Effect |
|---|---|
| `--remote URL` | Clone and pack a remote repository (URL or `owner/repo`). |
| `--remote-branch NAME` | Branch, tag, or commit to check out from the remote. |
| `--remote-trust-config` | Trust `gophercram.config.json` files inside the cloned repo. |

## Configuration

| Flag | Effect |
|---|---|
| `-c, --config PATH` | Path to a config file. `.json`, `.jsonc`, and `.json5` accepted. |
| `--init` | Generate a default config file and exit. |
| `--global` | With `--init`, write the config to the user-global location. |
| `--validate-config` | Load and validate the configuration without packing; exit 0 on success. |

## Security

| Flag | Effect |
|---|---|
| `--no-security-check` | Don't scan for embedded secrets. |

## Token counting

| Flag | Effect |
|---|---|
| `--token-count-encoding NAME` | Token estimator: `approx` (default), `cl100k_base` (embedded vocab), or `o200k_base` (lazy-fetched on first use, cached in `~/.cache/gophercram/`). |

## Watch

| Flag | Effect |
|---|---|
| `--watch-interval D` | Poll interval for `gophercram watch` (default `2s`; Go duration string). |

## Diagnostics

| Flag | Effect |
|---|---|
| `--cpu-profile FILE` | Write a Go CPU profile to FILE. |
| `--mem-profile FILE` | Write a Go heap profile to FILE on exit. |

## Meta

| Flag | Effect |
|---|---|
| `-v, --version` | Print the GopherCram version and exit. |
| `-h, --help` | Print the help screen and exit. |

## Exit codes

| Code | Meaning |
|------|---------|
| `0`  | Operation completed successfully. |
| `1`  | A runtime error occurred (file system, git, parse, …). |
| `2`  | Argument parsing failed. |

## Conventions

- Boolean flags may also be passed as `--flag=true`, `--flag=false`,
  `--flag=1`, etc.
- Use `--` to mark the end of options; subsequent tokens are treated as
  paths even if they begin with `-`.
- Size flags accept `b`, `kb`, `mb`, `gb` suffixes (decimal-friendly:
  `2.5mb`).

## Worked examples

```bash
# Pack everything under src/, drop binary files, write Markdown
gophercram src/ --style markdown -o src.md

# Strip comments, then compress for context-window economy
gophercram --remove-comments --compress -o slim.xml

# Pack with real tokenizer counts
gophercram --token-count-encoding cl100k_base .

# Emit a SKILL.md for use as a Claude Agent Skill
gophercram --style skill -o SKILL.md .

# Emit vectors for ingestion into a RAG pipeline
gophercram --style vectors -o vectors.json .

# Round-trip via extract
gophercram --output pack.xml .
gophercram extract pack.xml /tmp/restored

# Run as an MCP server (clients spawn the process over stdio)
gophercram mcp

# Watch the tree and repack on change
gophercram watch --watch-interval 1s

# Include open issues + PRs from a GitHub remote
gophercram --remote rajathjn/GopherCram --include-issues 5 --include-prs 5

# Use a custom config for a sub-package
gophercram --config configs/frontend.json client/
```