CLI Reference

Shard includes a full-featured CLI for scripting and automation.

Installation

The CLI is a separate binary from the desktop app. Both share the same data directory (~/.shard/), so profiles, accounts, and mods are shared between them.

Build from source


cd launcher
cargo build --release
# Binary: target/release/shard
 
# Or install to ~/.cargo/bin/
cargo install --path .

Homebrew (coming soon)


brew install shard-launcher

Global Options


shard <COMMAND>
 
Options:
  -h, --help     Print help
  -V, --version  Print version

Commands

Profile Management


# List all profiles
shard list
shard profile list
 
# Create a new profile
shard profile create "Profile Name" --mc 1.21.4
shard profile create "Modded" --mc 1.21.4 --loader fabric
shard profile create "Pinned" --mc 26.3 --loader fabric@0.19.5
shard profile create "NeoForge" --mc 26.3 --loader neoforge@latest

--loader accepts fabric, quilt, forge or neoforge, optionally followed by @<version>. A bare loader type is shorthand for <type>@latest. latest is resolved to a concrete version when the profile is created and stored in profile.json, so the loader does not change silently between launches (if it cannot be resolved, e.g. offline, latest is kept and resolved at launch).


# Rename a profile
shard profile rename "Old Name" "New Name"
 
# Delete a profile
shard profile delete "Profile Name"
 
# Show profile details
shard profile show "Profile Name"
 
# Clone a profile
shard profile clone "Source" "Destination"
 
# Compare two profiles
shard profile diff "Profile A" "Profile B"

Content Management


# Add mods to a profile
shard mod add "Profile" sodium
shard mod add "Profile" /path/to/mod.jar
 
# Remove mods
shard mod remove "Profile" sodium
 
# List mods in a profile
shard mod list "Profile"
 
# Resource packs and shader packs
shard resourcepack add "Profile" /path/to/pack.zip
shard shaderpack add "Profile" /path/to/shader.zip

Account Management


# Add a Microsoft account (device code flow)
shard account add
 
# List accounts
shard account list
 
# Set active account
shard account use <username>
 
# Remove an account
shard account remove <username>
 
# Show account info
shard account info
 
# Skin management
shard account skin upload /path/to/skin.png
shard account skin set-model slim
 
# Cape management
shard account cape list
shard account cape select <cape-id>

Store Operations


# Search for content
shard store search sodium
shard store search sodium --platform modrinth
shard store search jei --platform curseforge
 
# Get project info
shard store info <platform> <project-id>
 
# List project versions
shard store versions <platform> <project-id>
 
# Install content to a profile
shard store install "Profile" <platform> <project-id>

Library Management


# List library items
shard library list
shard library list --type mods
 
# Show item details
shard library show <hash>
 
# Import content
shard library import /path/to/file.jar
 
# Remove from library
shard library remove <hash>
 
# Update metadata
shard library update <hash>
 
# Show statistics
shard library stats
 
# Sync with content store
shard library sync
 
# Tag management
shard library tag add <hash> <tag>
shard library tag remove <hash> <tag>

Launch


# Launch a profile
shard launch "Profile Name"
 
# Launch with specific account
shard launch "Profile Name" --account <username>
 
# Prepare without launching (prints the launch plan; the access token is redacted)
shard launch "Profile Name" --prepare-only
 
# Keep the game window hidden (for automation with the MC-CLI mod 1.6.0+)
shard launch "Profile Name" --headless

--headless passes -Dmccli.headless=true and MCCLI_HEADLESS=1 to the game. The MC-CLI mod then creates the window hidden and keeps rendering, so mccli capture screenshots still work. On Linux servers without a display, the game still needs an OpenGL context: run it under a virtual display, for example xvfb-run shard launch "Profile Name" --headless.

Configuration


# Show current config
shard config show
 
# Set Microsoft OAuth credentials
shard config set-client-id <client-id>
shard config set-client-secret <client-secret>
 
# Set CurseForge API key
shard config set-curseforge-key <api-key>

App Updates


# Check the desktop app update manifest
shard app-update check
 
# Compare against a specific version (useful for testing updates)
shard app-update check --current 0.1.5
 
# Override the manifest endpoint or platform
shard app-update check --endpoint https://github.com/th0rgal/shard/releases/latest/download/latest.json
shard app-update check --platform darwin-aarch64

Logs


# View logs
shard logs

Templates


# Template management
shard template list
shard template create <name>
shard template apply <profile> <template>

Modpacks


# Modpack management
shard modpack import /path/to/modpack.mrpack
shard modpack export "Profile" /path/to/output.mrpack

Environment Variables

Variable	Description
`SHARD_MS_CLIENT_ID`	Microsoft OAuth client ID
`SHARD_MS_CLIENT_SECRET`	Microsoft OAuth client secret (if required)
`SHARD_CURSEFORGE_API_KEY`	CurseForge API key
`RUST_LOG`	Logging level (error, warn, info, debug, trace)

Examples

Create a modded profile


# Create profile
shard profile create "Modded 1.21" --mc 1.21.4 --loader fabric
 
# Add performance mods
shard mod add "Modded 1.21" sodium
 
# Launch
shard launch "Modded 1.21"

Batch operations


# Add mods to multiple profiles
for profile in "Profile A" "Profile B" "Profile C"; do
  shard mod add "$profile" sodium
done

Scripted backup


#!/bin/bash
# Backup all profiles
mkdir -p ~/shard-backup
cp -r ~/.shard/profiles ~/shard-backup/
cp ~/.shard/accounts.json ~/shard-backup/
echo "Backup complete!"