# Plakar Ptar

`plakar ptar` creates portable `.ptar` archives from data sources.

### Syntax

```bash
$ plakar ptar [options] -o output.ptar [sources]
```

### Required Arguments

| Argument | Description |
|----------|-------------|
| `-o path` | Output file path for the `.ptar` archive |
| sources | At least one: `-k location` for Kloset Store or filesystem path |

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-k location` | string | - | Include a Kloset Store (path or alias) |
| `-plaintext` | flag | false | Disable encryption |
| `-overwrite` | flag | false | Allow overwriting existing files |


### Source Types

| Source Type | Syntax | Example |
|-------------|--------|---------|
| Filesystem path | `/path` or `./path` | `/home/user/Documents` |
| Kloset Store (path) | `-k /path` | `-k $HOME/backups` |
| Kloset Store (alias) | `-k @alias` | `-k @s3-backups` |
| Remote protocols | Plugin-dependent | `sftp://`, `s3://`, `ipfs://` |

### Examples

```bash
# Single directory
$ plakar ptar -o documents.ptar /home/user/Documents

# Multiple paths
$ plakar ptar -o important.ptar /home/user/Documents /home/user/Pictures

# From Kloset Store
$ plakar ptar -o backup.ptar -k $HOME/backups

# From multiple stores
$ plakar ptar -o combined.ptar -k $HOME/backups -k @s3-backups

# Mixed sources
$ plakar ptar -o comprehensive.ptar -k $HOME/backups /home/user/NewDocs

# Plaintext archive
$ plakar ptar -plaintext -o unencrypted.ptar -k $HOME/backups

# Overwrite existing
$ plakar ptar -overwrite -o existing.ptar -k $HOME/backups
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `PLAKAR_PASSPHRASE` | Passphrase for archive encryption (avoids interactive prompt) |

### Exit Codes

| Code | Meaning |
|------|---------|
| 0    | Success |
| 1    | Error (file exists without `-overwrite`, invalid source, etc.) |

## plakar at ... (Ptar Operations)

Access Ptar files as read-only Kloset Stores.

### Syntax

```bash
$ plakar at archive.ptar <command>
```

### Supported Commands

| Command | Description |
|---------|-------------|
| `ls [snapshot-id]` | List snapshots or files in a snapshot |
| `check` | Verify cryptographic integrity |
| `restore -to destination [snapshot-id]` | Restore snapshot contents |
| `info` | Display archive metadata |

## plakar at ... ls

List snapshots or snapshot contents.

### Syntax

```bash
$ plakar at archive.ptar ls [snapshot-id]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| snapshot-id | No | If omitted, lists all snapshots; if provided, lists files in that snapshot |

### Examples

```bash
# List all snapshots
$ plakar at backup.ptar ls

# List files in specific snapshot
$ plakar at backup.ptar ls df42124a
```

### Output Format

**Snapshots:**

```bash
<timestamp> <snapshot-id> <size> <duration> <path>
```

**Files:**

```bash
<timestamp> <permissions> <user> <group> <size> <filename>
```

## plakar at ... check

Verify archive integrity.

### Syntax

```bash
$ plakar at archive.ptar check
```

### Examples

```bash
$ plakar at backup.ptar check
```

### Output

```bash
info: <snapshot-id>: ✓ <path>
```

## plakar at ... restore

Restore snapshot contents to filesystem or Kloset Store.

### Syntax

```bash
$ plakar at archive.ptar restore -to destination [snapshot-id]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `-to path` | Yes | Destination directory or Kloset Store alias (e.g., `@alias`) |
| snapshot-id | No | Snapshot to restore; defaults to first snapshot if omitted |

### Examples

```bash
# Restore to local directory
$ plakar at backup.ptar restore -to $HOME/restored-backups df42124a

# Restore to configured store
$ plakar at backup.ptar restore -to @new-location df42124a

# Restore first snapshot (no ID specified)
$ plakar at backup.ptar restore -to $HOME/restored
```

## plakar at ... info

Display archive metadata.

### Syntax

```bash
$ plakar at archive.ptar info
```

### Examples

```bash
$ plakar at backup.ptar info
```

## Passphrase Handling

### Interactive Mode

If `PLAKAR_PASSPHRASE` is not set, prompts appear:

**Creating archive:**

```bash
repository passphrase:
repository passphrase (confirm):
```

**Accessing archive:**

```bash
repository passphrase:
```

**Different source/destination:**

```bash
source repository passphrase:
repository passphrase:
repository passphrase (confirm):
```

### Non-interactive Mode

Set `PLAKAR_PASSPHRASE` environment variable to avoid prompts:

```bash
$ export PLAKAR_PASSPHRASE="your-secure-passphrase"
$ plakar ptar -o backup.ptar -k $HOME/backups
```

## File Format Properties

| Property | Value |
|----------|-------|
| Read-only | Yes (archives cannot be modified after creation) |
| Self-contained | Yes (includes all metadata and data) |
| Portable | Yes (single file can be moved/copied freely) |
| Encrypted by default | Yes (unless `-plaintext` specified) |
| Tamper-evident | Yes (cryptographic verification via `check`) |

## Further Reading
For a deeper dive into the philosophy and technical design of the format, check out the following posts on the Plakar blog:

- [It doesn't make sense to wrap modern data in a 1979 format, introducing .ptar](https://www.plakar.io/posts/2025-06-27/it-doesnt-make-sense-to-wrap-modern-data-in-a-1979-format-introducing-.ptar/)
- [Technical deep dive into .ptar: replacing .tgz for petabyte-scale S3 archives](https://www.plakar.io/posts/2025-06-30/technical-deep-dive-into-.ptar-replacing-.tgz-for-petabyte-scale-s3-archives/)
- [Kloset Store & Ptar design documentation](https://github.com/PlakarKorp/kloset/blob/main/encryption/README.md)