pakker/docs/COMMANDS.md

# Pakker Command Reference

Complete reference for all Pakker commands.

## Table of Contents

- [Global Options](#global-options)
- [Project Management](#project-management)
  - [init](#init)
  - [import](#import)
  - [add](#add)
  - [add-prj](#add-prj)
  - [rm](#rm)
  - [ls](#ls)
  - [inspect](#inspect)
- [Updates and Sync](#updates-and-sync)
  - [update](#update)
  - [fetch](#fetch)
  - [sync](#sync)
  - [status](#status)
- [Project Configuration](#project-configuration)
  - [set](#set)
  - [link](#link)
  - [unlink](#unlink)
- [Export](#export)
  - [export](#export-1)
- [Configuration](#configuration)
  - [cfg](#cfg)
  - [credentials](#credentials)
- [Remote Management](#remote-management)
  - [remote](#remote)
  - [remote-update](#remote-update)
  - [fork](#fork)
- [Utilities](#utilities)
  - [diff](#diff)

---

## Global Options

All commands support these global flags:

```bash
-v, --verbose     # Enable verbose output
-vv               # Very verbose (debug level)
-vvv              # Trace level logging
```

Examples:

```bash
pakker -v add sodium        # Info logging
pakker -vv fetch           # Debug logging
pakker -vvv export         # Trace logging
```

---

## Project Management

### init

Initialize a new modpack project in the current directory.

**Usage:**

```bash
pakker init [OPTIONS]
```

**Options:**

- `-t, --target <TARGET>` - Target platform (default: multiplatform)
- `-m, --mc-version <VERSION>` - Minecraft version (default: 1.20.1)
- `-l, --loader <LOADER>` - Mod loader (default: fabric)
- `--loader-version <VERSION>` - Specific loader version

**Examples:**

```bash
# Initialize Fabric 1.20.1 modpack
pakker init

# Initialize Forge 1.19.4 modpack
pakker init -m 1.19.4 -l forge

# Initialize with specific loader version
pakker init -l fabric --loader-version 0.15.0

# Initialize for CurseForge only
pakker init --target curseforge
```

**Output:**

Creates:
- `pakku.json` - Configuration file
- `pakku-lock.json` - Lockfile
- `overrides/` - Override directory

---

### import

Import an existing modpack from CurseForge or Modrinth.

**Usage:**

```bash
pakker import <SOURCE>
```

**Supported Formats:**

- CurseForge ZIP files
- Modrinth .mrpack files
- Local directories with manifest
- Remote URLs

**Examples:**

```bash
# Import from local file
pakker import modpack.zip
pakker import pack.mrpack

# Import from URL
pakker import https://example.com/modpack.zip

# Import from directory
pakker import ./existing-modpack/
```

---

### add

Interactively add projects to the modpack.

**Usage:**

```bash
pakker add <QUERY>...
```

**Features:**

- Interactive platform selection
- Automatic dependency resolution
- Fuzzy search with suggestions
- Version selection

**Examples:**

```bash
# Add single project
pakker add sodium

# Add multiple projects
pakker add sodium lithium phosphor

# Add with typo correction
pakker add sodum
# Suggests: Did you mean "sodium"?
```

---

### add-prj

Add projects non-interactively with explicit platform specification.

**Usage:**

```bash
pakker add-prj [OPTIONS] <PROJECT>
```

**Platform Options:**

- `--cf, --curseforge <ID>` - CurseForge project ID or slug
- `--mr, --modrinth <ID>` - Modrinth project ID or slug
- `--gh, --github <REPO>` - GitHub repository (format: owner/repo)

**Property Options:**

- `--type <TYPE>` - Project type (mod, resourcepack, shader, modpack)
- `--side <SIDE>` - Project side (client, server, both)
- `--strategy <STRATEGY>` - Update strategy (latest, specific, pinned)
- `--version <VERSION>` - Specific version to use
- `--redistributable <BOOL>` - Allow redistribution (true/false)
- `--subpath <PATH>` - Custom subpath in mods directory
- `--alias <NAME>` - Project alias
- `--export <BOOL>` - Include in exports (true/false)

**Control Options:**

- `--yes, -y` - Skip all confirmations
- `--no-deps` - Don't resolve dependencies

**Examples:**

```bash
# Add from Modrinth
pakker add-prj --mr sodium --yes

# Add from CurseForge
pakker add-prj --cf jei --yes

# Add from multiple platforms (creates unified project)
pakker add-prj --mr sodium --cf sodium --yes

# Add with custom properties
pakker add-prj --mr sodium --side client --strategy pinned --yes

# Add without dependencies (for CI)
pakker add-prj --mr fabric-api --yes --no-deps

# Add with alias
pakker add-prj --mr sodium --alias "sodium-mod" --yes

# Add GitHub release
pakker add-prj --gh "IrisShaders/Iris" --yes
```

**CI/CD Usage:**

```bash
#!/bin/bash
# Batch add mods
mods=(
  "fabric-api"
  "sodium"
  "lithium"
  "phosphor"
)

for mod in "${mods[@]}"; do
  pakker add-prj --mr "$mod" --yes --no-deps || exit 1
done

# Resolve all dependencies at once
pakker update --yes
```

---

### rm

Remove projects from the modpack.

**Usage:**

```bash
pakker rm <PROJECT>...
```

**Examples:**

```bash
# Remove single project
pakker rm sodium

# Remove multiple projects
pakker rm sodium lithium phosphor

# Remove with confirmation
pakker rm outdated-mod
```

---

### ls

List all projects in the modpack.

**Usage:**

```bash
pakker ls [OPTIONS]
```

**Options:**

- `--type <TYPE>` - Filter by type
- `--side <SIDE>` - Filter by side
- `--platform <PLATFORM>` - Filter by platform

**Examples:**

```bash
# List all projects
pakker ls

# List only mods
pakker ls --type mod

# List client-only projects
pakker ls --side client

# List CurseForge projects
pakker ls --platform curseforge
```

**Output Format:**

```
sodium (v0.5.0) - both - [CF, MR]
lithium (v0.11.2) - both - [CF, MR]
iris (v1.6.4) - client - [CF, MR]
```

---

### inspect

View detailed information about projects including dependencies.

**Usage:**

```bash
pakker inspect [PROJECT]...
```

**Features:**

- Project metadata (name, version, platforms)
- File information (name, size, hashes)
- Dependency trees with visualization
- Circular dependency detection
- Property display

**Examples:**

```bash
# Inspect single project
pakker inspect sodium

# Inspect multiple projects
pakker inspect sodium lithium phosphor

# View modpack overview (no arguments)
pakker inspect

# Fuzzy matching with suggestions
pakker inspect sodum
# Suggests: Did you mean "sodium"?
```

**Example Output:**

```
Sodium v0.5.0
  Type: mod
  Side: client
  Platforms: curseforge, modrinth
  
  Files:
    sodium-fabric-0.5.0+mc1.20.jar
    Size: 2.3 MB
    SHA1: abc123...
  
  Dependencies:
    └── fabric-api v0.87.0
        └── fabric-loader >=0.14.0
  
  Properties:
    Redistributable: true
    Update Strategy: latest
    Export: true
```

---

## Updates and Sync

### update

Update projects to newer versions.

**Usage:**

```bash
pakker update [PROJECT]... [OPTIONS]
```

**Options:**

- `--yes, -y` - Skip confirmations
- `--all` - Update all projects

**Examples:**

```bash
# Update specific project
pakker update sodium

# Update multiple projects
pakker update sodium lithium

# Update all projects
pakker update --all

# Update without confirmation (CI)
pakker update --all --yes
```

---

### fetch

Download all project files.

**Usage:**

```bash
pakker fetch [OPTIONS]
```

**Options:**

- `--force` - Re-download existing files

**Examples:**

```bash
# Fetch all files
pakker fetch

# Force re-download
pakker fetch --force
```

**Output:**

```
Fetching 42 files...
✓ sodium-fabric-0.5.0.jar (local)
✓ lithium-fabric-0.11.2.jar (download)
✓ fabric-api-0.87.0.jar (download)
...
```

---

### sync

Update projects and fetch files in one command.

**Usage:**

```bash
pakker sync [OPTIONS]
```

**Options:**

- `--yes, -y` - Skip confirmations

**Examples:**

```bash
# Sync everything
pakker sync

# Sync without confirmation
pakker sync --yes
```

Equivalent to:

```bash
pakker update --all --yes
pakker fetch
```

---

### status

Check for available updates.

**Usage:**

```bash
pakker status
```

**Examples:**

```bash
pakker status
```

**Example Output:**

```
Updates available:
  sodium: v0.5.0 → v0.5.1
  lithium: v0.11.1 → v0.11.2
  
No updates:
  fabric-api (v0.87.0)
  iris (v1.6.4)
```

---

## Project Configuration

### set

Modify project properties.

**Usage:**

```bash
pakker set <PROJECT> [OPTIONS]
```

**Options:**

- `--type <TYPE>` - Set project type
- `--side <SIDE>` - Set project side
- `--strategy <STRATEGY>` - Set update strategy
- `--version <VERSION>` - Set specific version (use with strategy=specific)
- `--redistributable <BOOL>` - Set redistributable flag
- `--subpath <PATH>` - Set custom subpath
- `--alias <NAME>` - Set project alias
- `--export <BOOL>` - Set export flag

**Examples:**

```bash
# Change project side
pakker set sodium --side client

# Pin to specific version
pakker set fabric-api --strategy specific --version 0.87.0

# Always update to latest
pakker set lithium --strategy latest

# Never update
pakker set custom-mod --strategy pinned

# Mark as non-redistributable
pakker set optifine --redistributable false

# Don't include in exports
pakker set dev-mod --export false

# Set custom subpath
pakker set performance-mod --subpath "mods/performance/"
```

---

### link

Link projects together (define relationships).

**Usage:**

```bash
pakker link <PROJECT> <TARGET>
```

**Examples:**

```bash
# Link projects
pakker link sodium fabric-api
```

---

### unlink

Remove project links.

**Usage:**

```bash
pakker unlink <PROJECT> <TARGET>
```

**Examples:**

```bash
# Unlink projects
pakker unlink sodium fabric-api
```

---

## Export

### export

Export modpack for distribution.

**Usage:**

```bash
pakker export [OPTIONS]
```

**Options:**

- `--profile <PROFILE>` - Export profile (curseforge, modrinth, serverpack, or custom)
- `-o, --output <PATH>` - Output file path

**Built-in Profiles:**

- `curseforge` - CurseForge ZIP format with manifest.json
- `modrinth` - Modrinth .mrpack format
- `serverpack` - Server-optimized pack (no client-only mods)

**Examples:**

```bash
# Export for CurseForge
pakker export --profile curseforge

# Export for Modrinth
pakker export --profile modrinth

# Export with custom output path
pakker export --profile curseforge -o dist/modpack-v1.0.0.zip

# Export server pack
pakker export --profile serverpack -o server.zip

# Export all formats
pakker export --profile curseforge -o dist/cf.zip
pakker export --profile modrinth -o dist/mr.mrpack
pakker export --profile serverpack -o dist/server.zip
```

**Profile Configuration:**

Configure profiles in `pakku.json`:

```json
{
  "exportProfiles": {
    "curseforge": {
      "filterPlatform": "curseforge",
      "includeNonRedistributable": false
    },
    "production": {
      "filterPlatform": "modrinth",
      "overrides": ["overrides", "prod-config"]
    }
  }
}
```

See [EXPORT_PROFILES.md](./EXPORT_PROFILES.md) for complete documentation.

---

## Configuration

### cfg

Configure modpack properties.

**Usage:**

```bash
pakker cfg [OPTIONS]
```

**Options:**

- `--name <NAME>` - Set modpack name
- `--version <VERSION>` - Set modpack version
- `--description <TEXT>` - Set description
- `--author <NAME>` - Set author

**Examples:**

```bash
# Set modpack name
pakker cfg --name "My Awesome Pack"

# Set version
pakker cfg --version "1.0.0"

# Set multiple properties
pakker cfg --name "Performance Pack" --author "YourName" --version "2.0.0"
```

---

### credentials

Manage platform API credentials.

**Usage:**

```bash
# View credentials
pakker credentials

# Set credentials
pakker credentials set --curseforge <KEY>
pakker credentials set --modrinth <TOKEN>

# Remove credentials
pakker credentials remove --curseforge
pakker credentials remove --modrinth
```

**Examples:**

```bash
# Set CurseForge API key
pakker credentials set --curseforge $CF_API_KEY

# Set Modrinth token
pakker credentials set --modrinth $MR_TOKEN

# View current credentials
pakker credentials

# Remove CurseForge key
pakker credentials remove --curseforge
```

**Credential Storage:**

Credentials are stored securely:
1. System keyring (if available)
2. Pakker credentials file (encrypted)
3. Environment variables

**Benefits:**

- Higher API rate limits
- Access to private/early-access mods
- Faster downloads
- Better error messages

---

## Remote Management

### remote

Manage Git remote repositories for modpack configuration.

**Usage:**

```bash
# Add remote
pakker remote add <NAME> <URL>

# List remotes
pakker remote list

# Remove remote
pakker remote remove <NAME>
```

**Examples:**

```bash
# Add origin remote
pakker remote add origin https://github.com/user/modpack.git

# Add upstream
pakker remote add upstream https://github.com/original/modpack.git

# List all remotes
pakker remote list

# Remove remote
pakker remote remove origin
```

---

### remote-update

Pull modpack configuration updates from remote Git repository.

**Usage:**

```bash
pakker remote-update [REMOTE]
```

**Examples:**

```bash
# Update from default remote
pakker remote-update

# Update from specific remote
pakker remote-update upstream

# Update and sync
pakker remote-update && pakker sync
```

---

### fork

Manage fork configuration.

**Usage:**

```bash
pakker fork [OPTIONS]
```

**Options:**

- `--ref <REF>` - Set fork reference (branch, tag, commit)
- `--type <TYPE>` - Set reference type

**Examples:**

```bash
# Fork from branch
pakker fork --ref main --type branch

# Fork from tag
pakker fork --ref v1.0.0 --type tag

# Fork from commit
pakker fork --ref abc1234 --type commit
```

---

## Utilities

### diff

Show differences between local and remote modpack configuration.

**Usage:**

```bash
pakker diff [REMOTE]
```

**Examples:**

```bash
# Show diff with default remote
pakker diff

# Show diff with specific remote
pakker diff upstream

# Show diff in detail
pakker -v diff
```

**Example Output:**

```
Changes in remote:
  + sodium v0.5.1 (added)
  - old-mod v1.0.0 (removed)
  ~ lithium v0.11.1 → v0.11.2 (updated)
  
Local changes:
  + custom-mod v1.0.0 (added)
```

---

## Common Patterns

### CI/CD Pipeline

```bash
#!/bin/bash
set -e

# Add projects non-interactively
pakker add-prj --mr fabric-api --yes --no-deps
pakker add-prj --mr sodium --yes --no-deps
pakker add-prj --mr lithium --yes --no-deps

# Resolve dependencies
pakker update --all --yes

# Fetch files
pakker fetch

# Export for all platforms
pakker export --profile curseforge -o dist/curseforge.zip
pakker export --profile modrinth -o dist/modrinth.mrpack
pakker export --profile serverpack -o dist/server.zip
```

### Batch Updates

```bash
# Update all projects
pakker update --all --yes

# Fetch new versions
pakker fetch

# Export updated pack
pakker export --profile modrinth -o updated-pack.mrpack
```

### Platform Migration

```bash
# Add projects from new platform
pakker add-prj --mr sodium --cf sodium --yes
pakker add-prj --mr lithium --cf lithium --yes

# Export for both platforms
pakker export --profile curseforge -o cf-pack.zip
pakker export --profile modrinth -o mr-pack.mrpack
```

---

## Environment Variables

### Credentials

```bash
export CURSEFORGE_API_KEY="your-key"
export MODRINTH_TOKEN="your-token"
```

### Verbosity

```bash
export PAKKER_LOG=debug  # or info, warn, error
```

### Cache

```bash
export PAKKER_CACHE_DIR="$HOME/.cache/pakker"
```

---

## Exit Codes

- `0` - Success
- `1` - General error
- `2` - Invalid arguments
- `3` - Project not found
- `4` - Network error
- `5` - File system error

---

## See Also

- [Main Documentation](./README.md)
- [Export Profiles](./EXPORT_PROFILES.md)
- [Migration Guide](./MIGRATION.md)
- [Examples](../examples/)