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
}