Palette TD

The official command-line tool for Palette. Clone project structures, pull promoted files to your local machine, and push new versions — all from the terminal.

Install

npm install -g @palette.tools/palette-td

Requires Node.js 18 or later.

Quick Start

palette login                # sign in via browser
palette clone                # select a project and create the local folder structure
cd <cloned-project>
palette pull                 # download promoted / latest files
palette push <file>          # upload a new version

Authentication

Browser sign-in (default)

palette login

Opens a browser window for device-based authentication. Credentials are saved to ~/.palette/credentials.json.

API key (CI / headless)

palette login --api-key <key>

Or set environment variables:

export PALETTE_API_KEY="your_api_key"
export PALETTE_BASE_URL="https://palette.tools"   # optional

Environment variables take priority over the stored credentials file.

Commands

palette login

Authenticate with Palette. Uses browser-based device auth by default; pass --api-key for headless environments.

| Flag | Description | | --- | --- | | --api-key <key> | Authenticate with an API key instead of the browser | | --base-url <url> | Override the server URL (default https://palette.tools) |

palette clone

Clone a project's folder structure locally. Creates a directory tree mirroring the project's categories and assets, plus a .palette/manifest.json that tracks sync state. No files are downloaded — run palette pull afterward.

| Flag | Description | | --- | --- | | --project-id <id> | Skip interactive project selection | | --path <dir> | Target directory (prompted when omitted) |

palette pull

Download new and updated files into a previously cloned project. Picks the promoted version for each version group (or the latest if nothing is promoted). Skips files that are already up to date based on the manifest.

Must be run from inside a cloned project directory (or a subdirectory of one).

| Flag | Description | | --- | --- | | --category <name> | Only pull files under this category | | --asset <name> | Only pull files under this asset | | --dry-run | List what would be downloaded without actually downloading |

palette push <file>

Upload a local file as a new version. When run interactively inside a cloned project, the CLI walks you through selecting (or creating) the target category, asset, task, and version group.

| Flag | Description | | --- | --- | | --project-id <id> | Target project (inferred from manifest when omitted) | | --category-id <id> | Target category (required in non-interactive mode) | | --asset-id <id> | Target asset | | --task-id <id> | Target task | | --version-group-id <id> | Target version group | | --message <msg> | Attach a push message | | --promote | Promote the version immediately after pushing |

palette context

Display the workspace and project tree for the signed-in account. When run inside a cloned project, it automatically scopes to that project and shows categories, assets, tasks, and version groups.

Alias: palette ls

| Flag | Description | | --- | --- | | --project-id <id> | Scope to a specific project | | --json | Output raw JSON |

palette whoami

Print the currently signed-in account name and email.

Alias: palette status

palette logout

Remove stored credentials from this machine.

Project Manifest

When you run palette clone, a .palette/manifest.json file is created in the project root. This file tracks which project the folder belongs to and which file versions have been pulled. Both pull and push read and update this manifest automatically.

Troubleshooting

• "You are not signed in" — Run palette login.
• "No .palette/manifest.json found" — You need to cd into a cloned project, or run palette clone first.
• Switching accounts — Run palette logout, then palette login.
• Wrong server — Pass --base-url to palette login or set PALETTE_BASE_URL.