CLI Reference

Complete command-line reference for @storysplat/splat-tools.

Installation

# Global installation
npm install -g @storysplat/splat-tools

# Or use npx for one-off commands
npx @storysplat/splat-tools <command>

Commands Overview

Command	Description
convert	Convert between splat formats
image2splat	Create splat from images
video2splat	Create 4DGS from video
info	Display splat file information
preview	Launch preview server
manifest	Generate 4DGS manifest

---

convert

Convert between Gaussian Splat formats.

Usage

splat-tools convert <input> [output] [options]

Arguments

Argument	Description
input	Input file path or glob pattern
output	Output file path (optional for batch)

Options

Option	Alias	Description	Default
--format	-f	Output format (sog, ply, splat)	Auto-detect
--quality	-q	Quality level (low, medium, high)	medium
--output-dir	-o	Output directory for batch	Same as input
--compress		Enable compression (PLY)	true
--overwrite		Overwrite existing files	false
--verbose	-v	Show detailed output	false

Examples

# Single file conversion
splat-tools convert scene.ply scene.sog

# Batch conversion
splat-tools convert "*.ply" --output-dir ./converted --format sog

# High quality SOG
splat-tools convert scene.ply scene.sog --quality high

# Verbose output
splat-tools convert scene.ply scene.sog --verbose

---

image2splat

Create a Gaussian Splat from a collection of images.

Usage

splat-tools image2splat --input <dir> --output <file> [options]

Options

Option	Alias	Description	Default
--input	-i	Input directory with images	Required
--output	-o	Output file path	Required
--preset	-p	Quality preset (fast, balanced, high)	balanced
--iterations		Training iterations	Preset-based
--format	-f	Output format (sog, ply)	sog
--gpu		GPU device ID or 'auto'	auto
--keep-temp		Keep intermediate files	false
--verbose	-v	Show detailed output	false

Presets

Preset	Iterations	Description
fast	3000	Quick results, lower quality
balanced	10000	Good balance of speed and quality
high	30000	Best quality, longer processing

Examples

# Basic usage
splat-tools image2splat --input ./photos --output scene.sog

# High quality
splat-tools image2splat -i ./photos -o scene.sog --preset high

# Custom iterations
splat-tools image2splat -i ./photos -o scene.ply --iterations 20000

# Specific GPU
splat-tools image2splat -i ./photos -o scene.sog --gpu 0

---

video2splat

Convert video to 4DGS frame sequence.

Usage

splat-tools video2splat --input <video> --output <dir> [options]

Options

Option	Alias	Description	Default
--input	-i	Input video file	Required
--output	-o	Output directory	Required
--fps		Frames per second	24
--start		Start time (seconds or HH:MM:SS)	0
--duration		Duration (seconds or HH:MM:SS)	Full video
--format	-f	Frame format (sog, ply)	sog
--quality	-q	Quality preset	balanced
--gpu		GPU device ID	auto
--parallel		Parallel frame processes	1
--manifest		Generate manifest.json	true
--verbose	-v	Show detailed output	false

Examples

# Basic conversion
splat-tools video2splat --input dance.mp4 --output ./dance-4dgs

# Specific FPS and duration
splat-tools video2splat -i video.mp4 -o ./output --fps 30 --duration 5

# Start at specific time
splat-tools video2splat -i video.mp4 -o ./output --start 01:30 --duration 10

# High quality with parallel processing
splat-tools video2splat -i video.mp4 -o ./output --quality high --parallel 2

---

info

Display information about a splat file.

Usage

splat-tools info <file> [options]

Options

Option	Alias	Description	Default
--json	-j	Output as JSON	false
--verbose	-v	Show all properties	false

Examples

# Basic info
splat-tools info scene.sog

# JSON output
splat-tools info scene.sog --json

# Verbose
splat-tools info scene.ply --verbose

Output

File: scene.sog
Format: SOG (StorySplat Optimized Gaussian)
Size: 45.2 MB
Gaussians: 523,456
Bounding Box: [-2.5, -1.0, -3.0] to [2.5, 3.0, 3.0]
Created: 2024-01-15T10:30:00Z

---

preview

Launch a local preview server for splat files.

Usage

splat-tools preview <file> [options]

Options

Option	Alias	Description	Default
--port	-p	Server port	3000
--host		Host address	localhost
--open	-o	Open browser automatically	true

Examples

# Preview file
splat-tools preview scene.sog

# Custom port
splat-tools preview scene.sog --port 8080

# Don't open browser
splat-tools preview scene.sog --no-open

---

manifest

Generate a manifest file for 4DGS frame sequences.

Usage

splat-tools manifest <directory> [options]

Options

Option	Alias	Description	Default
--output	-o	Output manifest path	./manifest.json
--fps		Playback FPS	24
--loop		Loop playback	true
--base-url		Base URL for frames	Empty

Examples

# Generate manifest
splat-tools manifest ./frames

# With base URL
splat-tools manifest ./frames --base-url https://cdn.example.com/4dgs/

# Custom FPS
splat-tools manifest ./frames --fps 30 --no-loop

Output

{
  "version": "1.0",
  "fps": 24,
  "loop": true,
  "frameCount": 120,
  "frames": [
    "frame_000.sog",
    "frame_001.sog",
    "..."
  ]
}

---

Global Options

These options work with all commands:

Option	Description
--help	Show help for command
--version	Show version number
--quiet	Suppress non-error output

Exit Codes

Code	Description
0	Success
1	General error
2	Invalid arguments
3	File not found
4	Processing error
5	GPU error

Environment Variables

Variable	Description
SPLAT_TOOLS_GPU	Default GPU device ID
SPLAT_TOOLS_QUALITY	Default quality preset
SPLAT_TOOLS_VERBOSE	Enable verbose output (1/0)

# Set defaults
export SPLAT_TOOLS_GPU=0
export SPLAT_TOOLS_QUALITY=high

Configuration File

Create ~/.splat-tools.json for persistent settings:

{
  "gpu": "auto",
  "quality": "balanced",
  "defaultFormat": "sog",
  "verbose": false
}