# narc: Nix Archive (NAR) Command-Line Utility

`narc` is an ergonomic command-line tool for manipulating Nix Archive (NAR) files. It provides easy creation and extraction of NAR files, with a focus on streamability, allowing for seamless integration into shell pipelines.

## Purpose

The Nix Archive (NAR) format is a simple, self-describing, and reproducible serialization format for file system trees used by the Nix package manager. While Nix itself provides some utilities for NAR manipulation, `narc` aims to offer a more user-friendly and stream-oriented interface, particularly addressing the ability to pack to standard output and unpack from standard input.

## Usage

### `pack` subcommand

To create a NAR archive from a file or directory:

```bash
narc pack <PATH> [--output <FILE>] [--compress <ALGORITHM>] [--level <LEVEL>]
```

- `<PATH>`: The path to the file or directory to pack.
- `--output <FILE>` or `-o <FILE>`: (Optional) The path to the output NAR file. If omitted, the NAR stream will be written to standard output (stdout).
- `--compress <ALGORITHM>` or `-c <ALGORITHM>`: (Optional) Specifies the compression algorithm to use. Supported algorithms: `gzip`, `zstd`. If omitted, no compression is used.
- `--level <LEVEL>` or `-l <LEVEL>`: (Optional) Specifies the compression level. For `gzip`, this is a value from 0 (no compression) to 9 (best compression). For `zstd`, this is a value from 0 (default) to 22 (best compression). If omitted, the default compression level for the chosen algorithm will be used.

**Examples:**

Pack a directory to a file with gzip compression at level 9:
```bash
narc pack my_directory -o my_archive.nar.gz --compress gzip --level 9
```

Pack a single file to stdout with zstd compression at level 10:
```bash
narc pack my_file.txt --compress zstd --level 10
```

**Examples:**

Pack a directory to a file:
```bash
narc pack my_directory -o my_archive.nar
```

Pack a single file to stdout:
```bash
narc pack my_file.txt
```

### `unpack` subcommand

To extract a NAR archive:

```bash
narc unpack [<FILE>] --output <DIR> [--decompress <ALGORITHM>]
```

- `[<FILE>]`: (Optional) The path to the input NAR file. If omitted, the NAR stream will be read from standard input (stdin).
- `--output <DIR>` or `-o <DIR>`: (Required) The directory to unpack the contents into. If the directory does not exist, it will be created. If it exists, the contents will be unpacked into it.
- `--decompress <ALGORITHM>` or `-d <ALGORITHM>`: (Optional) Specifies the decompression algorithm to use. Supported algorithms: `gzip`, `zstd`. If omitted, no decompression is performed.

**Examples:**

Unpack a gzip-compressed archive from a file:
```bash
narc unpack my_archive.nar.gz -o my_unpacked_directory --decompress gzip
```

Unpack a zstd-compressed archive from stdin to a directory:
```bash
cat my_archive.nar.zst | narc unpack -o my_unpacked_directory --decompress zstd
```

Pipe directly from `pack` to `unpack` with compression:
```bash
narc pack my_directory --compress zstd --level 15 | narc unpack -o my_unpacked_directory --decompress zstd
```

**Examples:**

Unpack an archive from a file:
```bash
narc unpack my_archive.nar -o my_unpacked_directory
```

Unpack from stdin to a directory:
```bash
cat my_archive.nar | narc unpack -o my_unpacked_directory
```

Pipe directly from `pack` to `unpack`:
```bash
narc pack my_directory | narc unpack -o my_unpacked_directory
```

## Gemini CLI Session Progress

This project is being developed with the assistance of the Gemini CLI. A detailed log of the development process, including implemented features, current state, and next steps, is maintained in `.gemini/GEMINI_PROGRESS.md`.