Command Line Interface (CLI)

Palette's CLI allows uploading source maps to Palette. It also supports automatically setting up your project with Palette.

Usage

palette <cmd> [args]

Commands:
  palette upload <dir> [opts]  Upload source maps to Palette
  palette setup                Setup your project with palette

Options:
  --version  Show version number                                       [boolean]
  --help     Show help                                                 [boolean]

Upload source maps

To upload source maps, specify the directory containing source maps. The asset key PALETTE_ASSET_KEY environment variable must be set to your asset key.

Get your asset key at https://palette.dev/[your-username]/[your-project]/settings

PALETTE_ASSET_KEY=a-123 npx @palette.dev/cli upload my/build/dir

Setting version

Use the --version flag to set the version of your build (see the versioning docs).

npx @palette.dev/cli upload my/build/dir --release --version v1.0.0

Mark version as a release

Use the --release flag to mark a version as a release (see the versioning docs).

npx @palette.dev/cli upload my/build/dir --release

Setup Script

Use Palette's setup script to automatically setup your project with Palette.

Only Next.js, Create React App, and vanilla react setups are supported at the moment.

npx @palette.dev/cli setup

Programmatic Usage

The CLI exports its core functions for use in code. This is how the Webpack and Vite plugins work internally.

Basic Example

import { init, upload } from "@palette.dev/cli";

const config = init(["./dist"], {
  key: process.env.PALETTE_ASSET_KEY,
  version: "1.0.0",
});

await upload(config);

API Reference

init(dirs, options)

Initializes the upload configuration.

Parameter	Type	Description
dirs	string[]	Directories to scan for source maps
options	PaletteOptions	Configuration options (see below)

Returns PaletteOptionsWithDirs - configuration object to pass to upload().

upload(config)

Uploads source maps to Palette.

Parameter	Type	Description
config	PaletteOptionsWithDirs	Configuration from init()

Returns Promise<void>.

PaletteOptions

Property	Type	Default	Description
key	string	(required)	Palette asset key
version	string	git commit hash	Version identifier (see versioning docs)
dryRun	boolean	true outside CI	Skip actual upload
endpoint	string	"https://palette.dev"	API endpoint
outputPath	string	process.cwd()	Base path for computing relative filenames
release	boolean	true on main/master	Mark as release version (see release docs)
silent	boolean	false	Suppress console output
concurrency	number	100	Maximum parallel uploads
git	object	auto-detected	Git metadata override
git.branch	string	from git or env	Branch name
git.hash	string	from git or env	Commit hash
git.message	string	from git	Commit message

Environment Behavior

• Disabled when NODE_ENV is "test" or "development" (unless PALETTE_TEST_ENV=true)
• dryRun defaults to true outside CI environments (when CI env var is not set)
• release automatically set to true when branch is main or master