@magicpixelart/cli 0.5.6 → 0.5.8

package/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.8] — 2026-08-26
+
+### Added
+
+- **Connect imports game sprites.** `sync` (and `sync --watch`) now runs `push`
+  automatically so connecting a game project imports existing sprites into the
+  MagicPixel library, flagged Sync to Unity so they appear under Connected.
+  `"push": false` in `magicpixel.json` opts out.
+- **First-connect import.** On Unity/Godot/GameMaker, PNGs under `Assets/` /
+  `assets/` / `datafiles/` are copied into `outDir` if they aren't there yet
+  (skipping Library/Temp/Packages, never overwriting) and then adopted.
+  Root-level PNGs (`hero.png`) adopt as a single-artboard document instead of
+  being skipped.
+
+## [0.5.7] — 2026-08-26
+
+### Added
+
+- **`magicpixel push`.** Two-way sync: walk `outDir`, hash local PNGs, and
+  upload changed or new sprites back to MagicPixel (`--dry-run`, `--flatten`).
+  Cloud conflicts refuse instead of overwriting; new on-disk files are adopted
+  into the library. Prune no longer deletes pending local sprites.
+- **Unity `.meta` files.** Sync writes TextureImporter `.meta` next to PNGs
+  (point filter, no compression, deterministic GUIDs). `unityPpu` (default 32)
+  and `unitySyncAll` in `magicpixel.json`. By default only artboards flagged
+  "Sync to Unity" in the editor are pulled.
+
+### Fixed
+
+- **`npx magicpixel …` dead end.** `magicpixel` is only the bin name — the
+  published package is `@magicpixelart/cli` — so hints like "run `npx
+  magicpixel init`" 404ed (`'magicpixel@*' is not in this registry`) for anyone
+  driving the CLI purely through `npx @magicpixelart/cli …`. Every user-facing
+  command hint now goes through a single `cmd()` helper that prints the short
+  `magicpixel <cmd>` form only when the package resolves from the project's
+  `node_modules`, and the always-correct `npx @magicpixelart/cli <cmd>` form
+  otherwise.
+- **Missing-config hint points at `start`.** A config-less project is now told
+  to run `start` (init + login + first sync) rather than bare `init`, which left
+  users unauthenticated with nothing on disk. `status` uses the same hint
+  (it previously hardcoded `npx @magicpixelart/cli init`).
+
 ## [0.5.6] — 2026-08-21
 
 ### Changed

package/README.md

@@ -19,7 +19,7 @@ Requires Node.js ≥ 18.
 One command, inside your project folder (the one with `package.json`):
 
 ```bash
-npx magicpixel start
+npx @magicpixelart/cli start
 ```
 
 That walks you through everything: detects your framework, writes `magicpixel.json`, prompts for your API key (paste it from [magicpixel.art/settings](https://magicpixel.art/settings) → API Keys), pulls your sprites, and tells you how to keep them fresh.
@@ -42,16 +42,16 @@ If `start` finds a `MAGICPIXEL_API_KEY` in your `.env` / `.env.local`, it offers
 ### Manual setup (advanced)
 
 ```bash
-npx magicpixel init           # writes magicpixel.json
-npx magicpixel login          # stores your key (or: export MAGICPIXEL_API_KEY=mp_live_...)
-npx magicpixel sync           # downloads changed assets
-npx magicpixel sync --watch   # keeps assets fresh while you work
+npx @magicpixelart/cli init           # writes magicpixel.json
+npx @magicpixelart/cli login          # stores your key (or: export MAGICPIXEL_API_KEY=mp_live_...)
+npx @magicpixelart/cli sync           # downloads changed assets
+npx @magicpixelart/cli sync --watch   # keeps assets fresh while you work
 ```
 
 ### Something not working?
 
 ```bash
-npx magicpixel doctor
+npx @magicpixelart/cli doctor
 ```
 
 Prints a one-screen diagnostic (CLI version, framework, outDir, key source, last sync, last error, live manifest probe). Paste it to your AI agent — it's designed to be the only context they need.
@@ -101,6 +101,7 @@ No bundler config, no runtime, no extra package.
 | `doctor` | Print a one-screen diagnostic — paste it to your AI agent when something breaks. |
 | `repair [--dry-run] [-y]` | Self-heal a broken sync: validate key → quarantine `state.json` → prune empty dirs → full re-sync. |
 | `sync [...flags]` | Fetch manifest, diff against disk, download changed assets, prune orphans. |
+| `push [--dry-run] [--flatten]` | Upload local PNG edits (and new sprites) back to MagicPixel. |
 | `add <glob>` / `remove <glob>` | Manage `include` patterns. |
 | `list` | Print matching manifest as a table. |
 | `status` | Config, last sync, diff vs remote. |
@@ -135,6 +136,9 @@ Sync is built to be cheap: a no-op run is one small manifest request, zero PNG b
 | `include`  | `string[]` | `["**/*"]`              | Globs (picomatch) matched against `folder/slug`. |
 | `exclude`  | `string[]` | `[]`                    | Globs to exclude.                                |
 | `emitIndex`| `boolean`  | `true`                  | Emit `<outDir>/index.ts` with typed asset map.   |
+| `unityPpu` | `number?`  | `32`                    | Unity only: pixels-per-unit in generated `.meta`. |
+| `unitySyncAll` | `boolean?` | `false`             | Unity only: sync every artboard, not just those flagged in the editor. |
+| `push`     | `boolean?` | `true`                  | Upload local PNG changes to MagicPixel on every `sync`. Set `false` for pull-only. |
 | `endpoint` | `string?`  | production URL          | Override the API base (testing only). Must be **HTTPS**. |
 
 State (`.magicpixel/state.json`) tracks `lastSync` (file mode `0600`). Add `.magicpixel/` to `.gitignore` (init offers to do this).

package/dist/api.js

@@ -1,6 +1,7 @@
 import { resolveEndpoint, getApiKey, CLI_VERSION } from './config.js';
-import { etagForSha256, MAX_ASSET_BYTES, readBodyWithLimit, safeFetch, } from './util/security.js';
+import { etagForSha256, MAX_ASSET_BYTES, readBodyWithLimit, safeFetch, validateEndpointUrl, } from './util/security.js';
 import { authHeaders } from './util/authHeaders.js';
+import { cmd } from './util/invoke.js';
 /**
  * Last-seen project metadata from any manifest response this process made.
  * Populated as a side-effect of `fetchManifestPage`; read by `whoami`,
@@ -38,7 +39,7 @@ export class ApiError extends Error {
 function friendly(status, body, context) {
     if (status === 401 || status === 403) {
         return (`${context}: ${status} — API key rejected.\n` +
-            `  Fix: regenerate at https://magicpixel.art/settings and re-run \`magicpixel login\`.`);
+            `  Fix: regenerate at https://magicpixel.art/settings and re-run \`${cmd('login')}\`.`);
     }
     if (status === 404) {
         return (`${context}: 404 — endpoint or asset not found.\n` +
@@ -279,3 +280,33 @@ export function retryAfterMsFromResponse(res) {
     }
     return 0;
 }
+/** Max sprites the server accepts per request (mirrors MAX_SPRITES_PER_REQUEST). */
+export const PUSH_BATCH_SIZE = 20;
+const DEFAULT_INGEST_ENDPOINT = 'https://magicpixel.art/api/public/integration/ingest';
+export function resolveIngestEndpoint() {
+    const override = process.env.MAGICPIXEL_INGEST_ENDPOINT?.trim();
+    return override ? validateEndpointUrl(override) : DEFAULT_INGEST_ENDPOINT;
+}
+/** Post one batch of sprites. Shares the transient-retry policy with pulls. */
+export async function pushSprites(sprites) {
+    const url = resolveIngestEndpoint();
+    return retryTransient('push', async () => {
+        const { headers, requestId } = buildHeaders({ 'Content-Type': 'application/json' });
+        const res = await safeFetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ sprites }),
+        });
+        const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        if (res.ok) {
+            const data = (await res.json());
+            const results = data && typeof data === 'object' ? data.results : undefined;
+            if (!Array.isArray(results)) {
+                throw new ApiError(502, withRequestId('push: unexpected server response shape (results missing).', serverRequestId), serverRequestId);
+            }
+            return results;
+        }
+        const bodyText = await res.text();
+        throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, 'push'), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
+    });
+}

package/dist/commands/doctor.js

@@ -8,6 +8,7 @@ import { detectProjectKind, hasPackageJson } from '../util/framework.js';
 import { safeFetch } from '../util/security.js';
 import { authHeaders } from '../util/authHeaders.js';
 import { CLI_VERSION } from '../version.js';
+import { cmd } from '../util/invoke.js';
 export async function doctorCommand(opts = {}) {
     const report = await collectDoctorReport(opts);
     if (opts.json) {
@@ -69,18 +70,18 @@ export async function collectDoctorReport(opts = {}) {
             : await probeManifest(endpoint);
     const suggestions = [];
     if (keySource === 'none')
-        suggestions.push('Run `magicpixel login` to store your API key.');
+        suggestions.push(`Run \`${cmd('login')}\` to store your API key.`);
     if (!config)
-        suggestions.push('Run `magicpixel start` (or `magicpixel init`) to bootstrap.');
+        suggestions.push(`Run \`${cmd('start')}\` (or \`${cmd('init')}\`) to bootstrap.`);
     if (config && !watchScript && pkgFound) {
-        suggestions.push('Add a `magicpixel:watch` npm script (or run `magicpixel sync -w`) for live sync.');
+        suggestions.push(`Add a \`magicpixel:watch\` npm script (or run \`${cmd('sync')} -w\`) for live sync.`);
     }
     if (state.lastError)
-        suggestions.push('Last sync surfaced an error — run `magicpixel repair` to self-heal.');
+        suggestions.push(`Last sync surfaced an error — run \`${cmd('repair')}\` to self-heal.`);
     // Only emit network-derived suggestions when we actually probed.
     if ('ok' in network && !network.ok) {
         if (network.status === 401 || network.status === 403) {
-            suggestions.push('API rejected the key — run `magicpixel login` with a fresh key from settings.');
+            suggestions.push(`API rejected the key — run \`${cmd('login')}\` with a fresh key from settings.`);
         }
         else if (network.status === null) {
             suggestions.push('Could not reach MagicPixel — check internet/proxy, or re-run with --offline.');
@@ -197,7 +198,7 @@ export function renderDoctorReport(r) {
         ? 'environment variable (MAGICPIXEL_API_KEY)'
         : r.key.source === 'credentials-file'
             ? '.magicpixel/credentials'
-            : kleur.yellow('none — run `magicpixel login`');
+            : kleur.yellow(`none — run \`${cmd('login')}\``);
     push(`API key source:     ${sourceLabel}`);
     push(`Watch script:       ${r.watchScript ? `"${r.watchScript}"` : kleur.dim('not configured')}`);
     push(`Last sync:          ${r.state.lastSync ? new Date(r.state.lastSync).toLocaleString() : kleur.dim('never')}`);
@@ -211,7 +212,7 @@ export function renderDoctorReport(r) {
     if ('skipped' in r.network) {
         const reason = r.network.skipped === 'offline'
             ? 'skipped (--offline)'
-            : 'skipped (no API key — run `magicpixel login`)';
+            : `skipped (no API key — run \`${cmd('login')}\`)`;
         push(`Network probe:      ${kleur.dim(reason)}`);
     }
     else if (r.network.ok) {

package/dist/commands/init.js

@@ -8,6 +8,7 @@ import { configPath, defaultConfig, saveConfig } from '../config.js';
 import { detectProjectKind, suggestOutDir, hasPackageJson, isStaticOutDir, supportsTypedIndex, isEngineKind, } from '../util/framework.js';
 import { assertSafeOutDir } from '../util/security.js';
 import { atomicWrite } from '../util/atomicWrite.js';
+import { cmd } from '../util/invoke.js';
 const WATCH_SCRIPT_NAME = 'magicpixel:watch';
 const WATCH_SCRIPT_CMD = 'magicpixel sync --watch';
 export async function initCommand(opts) {
@@ -100,13 +101,13 @@ export async function initCommand(opts) {
     if (interactive) {
         console.log();
         console.log(kleur.bold('Next:'));
-        console.log(`  1. ${kleur.dim('magicpixel login')}    ${kleur.dim('# paste your key from https://magicpixel.art/settings')}`);
-        console.log(`  2. ${kleur.dim('magicpixel sync')}     ${kleur.dim('# downloads your assets')}`);
+        console.log(`  1. ${kleur.dim(cmd('login'))}    ${kleur.dim('# paste your key from https://magicpixel.art/settings')}`);
+        console.log(`  2. ${kleur.dim(cmd('sync'))}     ${kleur.dim('# downloads your assets')}`);
         if (watchScriptAdded) {
             console.log(`  3. ${kleur.dim('npm run')} ${WATCH_SCRIPT_NAME}    ${kleur.dim('# keeps assets fresh while you edit')}`);
         }
         else {
-            console.log(`  3. ${kleur.dim('npx')} magicpixel sync --watch    ${kleur.dim('# keeps assets fresh while you edit')}`);
+            console.log(`  3. ${kleur.dim(`${cmd('sync')} --watch`)}    ${kleur.dim('# keeps assets fresh while you edit')}`);
         }
         console.log();
     }

package/dist/commands/push.js

@@ -0,0 +1,207 @@
+/**
+ * `magicpixel push` — disk → MagicPixel (the Unity → MagicPixel half of
+ * two-way sync).
+ *
+ * Walks `outDir`, hashes every PNG, and sends the ones that changed (or are
+ * brand new on disk) to `POST /api/public/integration/ingest`:
+ *
+ *   - known key + changed sha → write back into that artboard, using the sha
+ *     the CLI last pulled as the conflict baseline. If the cloud moved on the
+ *     server refuses with `conflict` and nothing is lost.
+ *   - unknown key            → adopt: the server mirrors the disk folders into
+ *     the library and appends/creates the document.
+ */
+import kleur from 'kleur';
+import ora from 'ora';
+import { mkdir, readFile, rename } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { relative, resolve } from 'node:path';
+import { loadConfig, loadState, saveState } from '../config.js';
+import { PUSH_BATCH_SIZE, pushSprites } from '../api.js';
+import { fileSha256 } from '../util/hash.js';
+import { assetDiskPathFromKey, walkOutDirPngs } from '../util/paths.js';
+import { planPush } from '../util/pushPlan.js';
+import { cmd } from '../util/invoke.js';
+import { detectProjectKind } from '../util/framework.js';
+import { importNearbyGamePngs } from '../util/gameScan.js';
+export async function pushCommand(opts = {}) {
+    await runPush(opts);
+}
+/**
+ * Scan local PNGs and upload new/changed ones into the MagicPixel library.
+ * Used by `magicpixel push` and by `sync` (so connect/watch imports game
+ * sprites without a second command).
+ */
+export async function runPush(opts = {}) {
+    const config = await loadConfig();
+    const state = await loadState();
+    return runPushWith(config, state, opts);
+}
+export async function runPushWith(config, state, opts = {}) {
+    const quiet = opts.quiet === true;
+    const empty = { created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0, imported: 0 };
+    const spinner = quiet ? null : ora('Scanning local sprites…').start();
+    const kind = await detectProjectKind();
+    const scan = await importNearbyGamePngs(config.outDir, kind);
+    const imported = scan.copied;
+    const disk = await walkOutDirPngs(config.outDir);
+    const absByKey = new Map(disk.map((a) => [a.key, a.abs]));
+    const candidates = [];
+    for (const asset of disk) {
+        const sha = await fileSha256(asset.abs);
+        if (!sha)
+            continue;
+        candidates.push({
+            key: asset.key,
+            segments: asset.key.split('/'),
+            diskSha256: sha,
+        });
+    }
+    const actions = planPush(candidates, state.synced, { flatten: opts.flatten });
+    const skipped = actions.filter((a) => a.kind === 'skip' && a.reason !== 'legacy').length;
+    const legacy = actions.filter((a) => a.kind === 'skip' && a.reason === 'legacy');
+    const flattenBlocked = actions.filter((a) => a.kind === 'needs-flatten');
+    const sendable = actions.filter((a) => a.kind === 'update' || a.kind === 'adopt');
+    spinner?.succeed(`Local sprites: ${candidates.length} · to push ${sendable.length} · unchanged ${skipped}` +
+        (imported ? ` · imported ${imported}` : ''));
+    if (legacy.length > 0 && !quiet) {
+        console.log();
+        console.log(kleur.yellow(`! ${legacy.length} sprite${legacy.length === 1 ? '' : 's'} came from a legacy single-image file — skipped.`));
+        console.log(kleur.dim(`  Fix: open the file in MagicPixel and save it once, then re-run \`${cmd('sync')}\`.`));
+    }
+    if (flattenBlocked.length > 0 && !quiet) {
+        console.log();
+        console.log(kleur.yellow(`! ${flattenBlocked.length} sprite${flattenBlocked.length === 1 ? '' : 's'} would flatten a multi-layer artboard — skipped.`));
+        for (const a of flattenBlocked.slice(0, 10)) {
+            console.log(kleur.dim(`    ${a.key} (${'layers' in a ? a.layers : '?'} layers)`));
+        }
+        console.log(kleur.dim('  Fix: re-run with --flatten to replace them with the flat disk image.'));
+    }
+    if (sendable.length === 0) {
+        if (!quiet)
+            console.log(kleur.green('✓ nothing to push.'));
+        return { ...empty, imported, unchanged: skipped };
+    }
+    if (opts.dryRun) {
+        if (!quiet) {
+            console.log();
+            for (const a of sendable) {
+                const verb = a.kind === 'update' ? kleur.yellow('~') : kleur.green('+');
+                console.log(`  ${verb} ${a.key}${a.kind === 'adopt' ? kleur.dim(' (new)') : ''}`);
+            }
+            console.log(kleur.dim('--dry-run: nothing sent.'));
+        }
+        return { ...empty, imported };
+    }
+    const outRoot = resolve(process.cwd(), config.outDir);
+    const shaByKey = new Map(candidates.map((c) => [c.key, c.diskSha256]));
+    const sprites = [];
+    for (const a of sendable) {
+        const abs = absByKey.get(a.key);
+        if (!abs)
+            continue;
+        const pngBase64 = (await readFile(abs)).toString('base64');
+        const diskSha256 = shaByKey.get(a.key);
+        if (a.kind === 'update') {
+            sprites.push({
+                key: a.key,
+                pngBase64,
+                diskSha256,
+                assetId: a.assetId,
+                layerIdx: a.layerIdx,
+                baseSha256: a.baseSha256,
+                flatten: opts.flatten === true,
+            });
+        }
+        else if (a.kind === 'adopt') {
+            sprites.push({ key: a.key, pngBase64, diskSha256, path: a.path, pathNames: a.pathNames, name: a.name });
+        }
+    }
+    const progress = quiet ? null : ora(`Pushing 0/${sprites.length}…`).start();
+    const results = [];
+    for (let i = 0; i < sprites.length; i += PUSH_BATCH_SIZE) {
+        const batch = sprites.slice(i, i + PUSH_BATCH_SIZE);
+        const batchResults = await pushSprites(batch);
+        results.push(...batchResults);
+        if (progress)
+            progress.text = `Pushing ${Math.min(i + batch.length, sprites.length)}/${sprites.length}…`;
+    }
+    const counts = { created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0 };
+    const nextSynced = { ...(state.synced ?? {}) };
+    for (const r of results) {
+        counts[r.status] = (counts[r.status] ?? 0) + 1;
+        const stateKey = r.cloudKey && r.cloudKey !== r.key ? r.cloudKey : r.key;
+        if (stateKey !== r.key && (r.status === 'created' || r.status === 'updated')) {
+            await renameLocalSprite(config.outDir, r.key, stateKey);
+        }
+        if ((r.status === 'created' || r.status === 'updated' || r.status === 'unchanged') && r.assetId && r.sha256) {
+            if (stateKey !== r.key)
+                delete nextSynced[r.key];
+            nextSynced[stateKey] = {
+                assetId: r.assetId,
+                layerIdx: typeof r.layerIdx === 'number' ? r.layerIdx : (nextSynced[stateKey]?.layerIdx ?? 0),
+                sha256: r.sha256,
+                layers: 1,
+            };
+        }
+    }
+    await saveState({ ...state, synced: nextSynced });
+    const failed = counts.conflict + counts.error;
+    const summary = `created ${counts.created}, updated ${counts.updated}, unchanged ${counts.unchanged}` +
+        (counts.conflict ? `, conflicts ${counts.conflict}` : '') +
+        (counts.error ? `, errors ${counts.error}` : '');
+    if (progress) {
+        if (failed)
+            progress.warn(`Push finished with issues. ${summary}`);
+        else
+            progress.succeed(`Pushed. ${summary}`);
+    }
+    if (!quiet) {
+        for (const r of results) {
+            if (r.status === 'conflict') {
+                console.log(`  ${kleur.yellow('!')} ${r.key}: ${conflictHint(r.reason)}`);
+            }
+            else if (r.status === 'error') {
+                console.log(`  ${kleur.red('!')} ${r.key}: ${r.message ?? 'push failed'}`);
+            }
+        }
+        if (counts.created > 0) {
+            console.log(kleur.dim(`  ${counts.created} new sprite${counts.created === 1 ? '' : 's'} now live in your MagicPixel library ` +
+                `(folders mirrored from ${relative(process.cwd(), outRoot)}). Refresh the library to see them.`));
+        }
+    }
+    if (failed)
+        process.exitCode = 1;
+    return { ...counts, imported };
+}
+function conflictHint(reason) {
+    switch (reason) {
+        case 'cloud-changed':
+            return `changed in MagicPixel since the last sync — run \`${cmd('sync')}\` first, then re-push.`;
+        case 'would-flatten':
+            return 'artboard has multiple layers or frames — re-run with --flatten to replace it.';
+        case 'legacy-document':
+            return 'document predates layer storage — open and save it once in MagicPixel.';
+        case 'not-found':
+            return `artboard no longer exists in MagicPixel — run \`${cmd('sync')}\` to refresh.`;
+        default:
+            return `conflict — run \`${cmd('sync')}\` and try again.`;
+    }
+}
+/**
+ * Move a pushed sprite (and its `.meta` sidecar) to the disk path matching the
+ * key the cloud assigned. Best effort: a failed move only means the next sync
+ * re-downloads the sprite under its cloud name.
+ */
+async function renameLocalSprite(outDir, fromKey, toKey) {
+    const from = assetDiskPathFromKey(outDir, fromKey);
+    const to = assetDiskPathFromKey(outDir, toKey);
+    try {
+        await mkdir(dirname(to), { recursive: true });
+        await rename(from, to);
+        await rename(`${from}.meta`, `${to}.meta`).catch(() => { });
+    }
+    catch {
+        // Leave the file where it is; sync reconciles.
+    }
+}

package/dist/commands/repair.js

@@ -8,9 +8,10 @@ import { loadConfig, statePath, getApiKey } from '../config.js';
 import { assertKeyValid } from '../util/auth.js';
 import { listEmptyDirs, pruneEmptyDirs } from '../util/paths.js';
 import { syncCommand } from './sync.js';
+import { cmd } from '../util/invoke.js';
 /**
  * One-shot self-healing command. Runs the standard "turn it off and on
- * again" recovery sequence so support can say "run `npx magicpixel repair`":
+ * again" recovery sequence so support can say "run `npx @magicpixelart/cli repair`":
  *
  *   1. Validate the stored API key.
  *   2. Quarantine `state.json` so the next sync re-derives everything.
@@ -117,7 +118,7 @@ export async function repairCommand(opts = {}) {
         console.log(kleur.dim('     (state was not reset — this will run a normal full sync, not a recovery)'));
     }
     if (opts.dryRun) {
-        console.log(`     ${kleur.dim('would run `magicpixel sync --full` (skipped in --dry-run)')}`);
+        console.log(`     ${kleur.dim(`would run \`${cmd('sync')} --full\` (skipped in --dry-run)`)}`);
         console.log();
         if (skippedStep2) {
             console.log(kleur.yellow('! repair plan would skip the state reset. Re-run with --yes to apply it.'));
@@ -137,7 +138,7 @@ export async function repairCommand(opts = {}) {
     await syncCommand({ full: true, prune: true });
     console.log();
     if ((process.exitCode ?? 0) > exitBefore) {
-        console.log(kleur.yellow('! repair completed with errors — re-run `magicpixel sync` to retry the failed downloads.'));
+        console.log(kleur.yellow(`! repair completed with errors — re-run \`${cmd('sync')}\` to retry the failed downloads.`));
     }
     else {
         console.log(kleur.green('✓ repair complete.'));

package/dist/commands/start.js

@@ -10,24 +10,20 @@ import { findKeyInDotenv, readCredentialsSync, writeCredentials } from '../util/
 import { initCommand } from './init.js';
 import { loginCommand } from './login.js';
 import { syncCommand } from './sync.js';
+import { cmd } from '../util/invoke.js';
 /**
  * One-command bootstrap for new users. Runs init → key prompt → first sync →
  * prints copy-pasteable watch instructions. Designed so a non-technical user
- * can paste `npx magicpixel start` and end up with sprites on disk and a watch
- * script ready to run.
+ * can paste `npx @magicpixelart/cli start` and end up with game sprites in
+ * MagicPixel (and flagged sprites back on disk) plus a watch script.
  */
 export async function startCommand(opts = {}) {
     console.log(kleur.bold('🪄  MagicPixel — first-run setup'));
-    console.log(kleur.dim('  This walks you through getting your sprites onto disk.'));
+    console.log(kleur.dim('  This connects your game project so existing sprites show up in MagicPixel.'));
     console.log();
-    // 1. `start` is JS-only — engine projects use init + login + sync --watch.
-    if (!hasPackageJson()) {
-        const kind = await detectProjectKind();
-        if (isEngineKind(kind)) {
-            console.log(kleur.yellow(`  Detected ${kind}. \`magicpixel start\` is JS-only; run ` +
-                '`npx magicpixel init && npx magicpixel login && npx magicpixel sync --watch` instead.'));
-            return;
-        }
+    const kind = await detectProjectKind();
+    // Engine projects have no package.json requirement. JS projects still need one.
+    if (!hasPackageJson() && !isEngineKind(kind)) {
         console.log(kleur.yellow('  MagicPixel needs a JavaScript project (package.json) to sync into.\n' +
             '  Run this inside your project folder — the one with package.json.'));
         return;
@@ -46,7 +42,7 @@ export async function startCommand(opts = {}) {
             console.log(kleur.yellow(`  Existing magicpixel.json is invalid:`));
             for (const line of msg.split('\n'))
                 console.log(kleur.yellow(`    ${line}`));
-            console.log(kleur.dim('  Re-run `npx magicpixel start --force` to overwrite it, or fix the file by hand.'));
+            console.log(kleur.dim(`  Re-run \`${cmd('start')} --force\` to overwrite it, or fix the file by hand.`));
             return;
         }
     }
@@ -73,7 +69,7 @@ export async function startCommand(opts = {}) {
     //    failures without throwing — snapshot around the call so we don't
     //    print a misleading green "you're set up" over a half-failed run.
     console.log();
-    console.log(kleur.bold('Step: first sync'));
+    console.log(kleur.bold('Step: import + sync'));
     const exitBefore = process.exitCode ?? 0;
     await syncCommand({ full: true });
     const firstSyncFailed = (process.exitCode ?? 0) > exitBefore;
@@ -84,7 +80,7 @@ export async function startCommand(opts = {}) {
     console.log();
     if (firstSyncFailed) {
         console.log(kleur.yellow('! first sync completed with errors.'));
-        console.log(kleur.dim('  Re-run `npx magicpixel sync` to retry the failed downloads, or `npx magicpixel doctor` to diagnose.'));
+        console.log(kleur.dim(`  Re-run \`${cmd('sync')}\` to retry the failed downloads, or \`${cmd('doctor')}\` to diagnose.`));
     }
     else {
         console.log(kleur.bold('You\'re set up. ✨'));
@@ -95,11 +91,11 @@ export async function startCommand(opts = {}) {
         console.log(`  ${kleur.green('▶')} ${kleur.bold('npm run magicpixel:watch')}   ${kleur.dim('# keeps sprites fresh while you edit them in MagicPixel')}`);
     }
     else {
-        console.log(`  ${kleur.green('▶')} ${kleur.bold('npx magicpixel sync --watch')}   ${kleur.dim('# keeps sprites fresh while you edit them in MagicPixel')}`);
+        console.log(`  ${kleur.green('▶')} ${kleur.bold(`${cmd('sync')} --watch`)}   ${kleur.dim('# keeps sprites fresh while you edit them in MagicPixel')}`);
     }
     console.log();
     if (await hasDevScript()) {
-        const watchCmd = hasWatch ? 'npm run magicpixel:watch' : 'npx magicpixel sync --watch';
+        const watchCmd = hasWatch ? 'npm run magicpixel:watch' : `${cmd('sync')} --watch`;
         console.log(kleur.dim('  Tip: run your dev server and the watcher together with'));
         console.log(kleur.dim(`       \`npx concurrently "npm run dev" "${watchCmd}"\``));
         console.log();

package/dist/commands/status.js

@@ -5,6 +5,7 @@ import { fileSha256 } from '../util/hash.js';
 import { assetDiskPath } from '../util/paths.js';
 import { readKeyForDisplay } from '../util/credentials.js';
 import { createLimit } from '../util/limit.js';
+import { cmd } from '../util/invoke.js';
 export async function statusCommand() {
     // Config is optional — a brand-new user can `magicpixel status` to inspect
     // their key/env before bothering with init. Mirrors `whoami` / `login`.
@@ -25,7 +26,7 @@ export async function statusCommand() {
     }
     else {
         console.log(kleur.yellow(`  magicpixel.json: ${configErr ?? 'missing'}`));
-        console.log(kleur.dim(`  Run \`npx magicpixel init\` to create one.`));
+        console.log(kleur.dim(`  Run \`${cmd('start')}\` to create one.`));
     }
     console.log();
     const state = await loadState();
@@ -40,7 +41,7 @@ export async function statusCommand() {
     // env var and falsely reported "key not set" for logged-in users.
     const stored = readKeyForDisplay();
     if (!stored) {
-        console.log(kleur.red('  no API key — run `magicpixel login` or set MAGICPIXEL_API_KEY'));
+        console.log(kleur.red(`  no API key — run \`${cmd('login')}\` or set MAGICPIXEL_API_KEY`));
         return;
     }
     const sourceLabel = stored.source === 'env' ? 'env (MAGICPIXEL_API_KEY)' : 'file (.magicpixel/credentials)';