npm package: @palette.tools/palette-td
Description: Palette CLI — push, pull, and manage creative assets from your terminal
Latest version: 0.1.4

# Palette TD

The official command-line tool for [Palette](https://palette.tools). Clone project structures, pull promoted files to your local machine, and push new versions — all from the terminal.

## Install

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

Requires **Node.js 18** or later.

## Quick Start

```bash
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)

```bash
palette login
```

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

### API key (CI / headless)

```bash
palette login --api-key <key>
```

Or set environment variables:

```bash
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`.