# Toolcraft CLI

Create standalone Toolcraft apps from the command line.

Toolcraft is a Pixel Point starter kit and UI/runtime library for building
personal creative design tools with AI. It gives generated apps a ready canvas,
control panel, export flow, AI workflow instructions, and verification checks so
you can focus prompts on the visual idea instead of rebuilding common creative
tool plumbing.

You use Toolcraft when a custom tool is faster or clearer than forcing a broad
design app to fit one specific job: procedural graphics, image effects, branded
asset generators, animation controllers, shader experiments, or quick visual
tools for client work.

## Usage

```bash
npx @pixel-point/toolcraft create
```

The create command uses the current directory when no target directory is passed, prompts for missing project values in an interactive terminal, generates the app, runs dependency installation with the package manager that launched the CLI, then prints the command to start the dev server.

After dependencies are installed, Toolcraft installs external workflow skills
in a batch through the `skills` CLI. The skill installer uses the same agent,
scope, and installation prompts as `npx skills add`. These skills improve the
agent workflow, while the generated app's signed local `AGENTS.md` and
`docs/toolcraft/*` remain the mandatory self-contained contract. `--no-skills`
therefore skips installation without disabling local verification.

Example:

```bash
npx @pixel-point/toolcraft create my-ascii-tool
cd my-ascii-tool
npm run dev
```

Then open the generated folder in Codex, Claude Code, Cursor, or another AI
coding agent and prompt for the creative output you want, for example:

```text
Build an app that applies an ASCII effect to an uploaded image.
```

## Start from an example

Choose an official example and enter a project name at the usual prompt:

```bash
npx @pixel-point/toolcraft create --template ascii
```

Template creation shares the blank starter's project-name and destination
behavior. In an empty directory it creates the project there. In a nonempty
directory, entering a project name creates a child directory with that name.
Use a positional destination or `--dir` to choose a location explicitly;
`--name` supplies the package name, and `--yes` uses defaults without prompts.

You can also use a standalone Toolcraft app from any GitHub owner:

```bash
npx @pixel-point/toolcraft create my-tool --template owner/repository
npx @pixel-point/toolcraft create my-tool --template owner/repository/examples/poster
npx @pixel-point/toolcraft create --template https://github.com/pixel-point/toolcraft/tree/main/examples/ascii
npx @pixel-point/toolcraft create --template owner/repository/examples/poster --ref feature/new-renderer
npx @pixel-point/toolcraft create --template git@github.com:owner/private-app.git
npx @pixel-point/toolcraft create --template ./my-local-template
```

`--ref` selects a branch, tag, or full commit SHA. For ambiguous GitHub tree URLs,
use `owner/repository/directory --ref <revision>`. Private sources use existing
Git credentials, with an authenticated GitHub CLI credential helper and SSH as
fallbacks. Git is required for remote templates. Templates that use Git LFS also
require Git LFS and access to the source assets.

Discover templates without creating a project or installing anything:

```bash
npx @pixel-point/toolcraft templates
npx @pixel-point/toolcraft templates owner/repository
npx @pixel-point/toolcraft templates owner/repository --ref v1.2.0 --json
```

Official names resolve to `pixel-point/toolcraft/examples/<name>`; publishing
another standalone example there does not require a CLI release. Repository
discovery checks the selected root, immediate child directories, and
`examples/*`, `templates/*`, and `apps/*`. Deeper directories work when selected
explicitly. Collections with multiple templates prompt for one selection;
`--yes` and noninteractive use require an exact source instead of choosing the
first result. `--all` continues to apply only to skill installation.

Templates are complete app snapshots. Their framework code, assets, defaults,
scripts, license, and dependency pins are preserved. The new package name is
applied to `package.json` and npm lockfile root metadata; existing product titles
and application IDs remain unchanged. Source Git history, generated skills,
local verification receipts, deployment linkage, private `.env` files, and
install/build output are omitted. `.env.example` is retained. A new
`toolcraft-source.json` records the source and resolved commit without attaching
an upstream Git remote or enabling automatic updates.

The template's declared package manager or lockfile takes precedence over the
CLI launcher. Locked npm apps use `npm ci`; locked pnpm apps use
`pnpm install --frozen-lockfile`. Conflicting package managers and stale locks
produce errors instead of silently rewriting dependency resolutions. Use
`--no-install` to copy the project without executing project code; unsupported
package managers require this flag and manual installation. Dependency lifecycle
scripts run during the dependency installation stage. Existing agent skill flags
and `--no-skills` work with template creation too.

Supported snapshots include the original unversioned hash manifest, legacy
manifest version 1, and signed version 3. Historical Creative Apps Kit snapshots
retain their original runtime paths and workflow when cloned.
Legacy apps keep their historical workflow; some require workflow skills for
`ai:check`, so `--no-skills` can leave that old check unsatisfied. Copying a
snapshot does not upgrade its framework or certify it against a newer contract.

For template authors: include the full standalone app, runtime/UI trees,
`src/app/app-schema.ts`, `src/app/app-composition.tsx`, local Toolcraft docs,
license/notice files, and the original integrity manifest. Legacy apps may
use `src/routes/index.tsx` instead of a composition entry. No extra registry
manifest is needed. Dependencies and imports must stay within the selected app
or reference external packages; workspace-only dependencies, source symlinks,
unexpanded submodules, and missing LFS assets are rejected. Framework integrity
is checked by the CLI without executing scripts from the downloaded repository.

For new blank apps, the generated bootstrap, route host, runtime copy, contract docs, and verification
reporter are signed platform files. Product code stays open through a typed
`appComposition` (`schema`, `canvasContent`, custom renderers, panel actions, and
default-media choice), while AST and runtime-evidence checks prevent replacing
the shell or satisfying acceptance/performance with source-code-shaped stubs.

Scripted usage:

```bash
npx @pixel-point/toolcraft create my-toolcraft-app --name my-toolcraft-app --yes --force
```

Generation is transactional. Toolcraft assembles the app in a sibling staging directory, runs dependency-free local-doc and signed platform-integrity validation there, then promotes it with an atomic rename. A failed new generation leaves no target. With `--force`, an ordinary existing folder is staged as the merge base so non-colliding files and `.git` keep the documented behavior; disposable install, build, coverage, and browser-report directories are not duplicated. A semantic-validation, pre-commit, or swap failure preserves the original folder and removes transaction artifacts. Existing generated Toolcraft apps are still never migrated in place.

Toolcraft detects `npm` and `pnpm` from the package manager user agent. For example, `npx @pixel-point/toolcraft create` generates npm-flavored setup commands, while `pnpm dlx @pixel-point/toolcraft create` generates pnpm-flavored setup commands.

Install Toolcraft skills to specific agents or locations:

```bash
npx @pixel-point/toolcraft create my-toolcraft-app --agent codex --agent claude-code
npx @pixel-point/toolcraft create my-toolcraft-app --agent codex --global
npx @pixel-point/toolcraft create my-toolcraft-app --all
npx @pixel-point/toolcraft create my-toolcraft-app --no-skills
```

Local source test without publishing:

```bash
mkdir -p /tmp/toolcraft-local-cli-test
cd /tmp/toolcraft-local-cli-test
node /Users/alex/Projects/primeui-v2/cli/bin/toolcraft.mjs --name local-cli-test --yes --force --no-install --no-skills
```

Local tarball test, matching the published package layout:

```bash
cd cli
npm pack --pack-destination /tmp
cd ..
TOOLCRAFT_SKIP_INSTALL=1 TOOLCRAFT_SKIP_SKILLS=1 npm exec --package /tmp/pixel-point-toolcraft-0.0.10.tgz -- toolcraft create /tmp/toolcraft-pack-exec-test --name pack-exec-test --yes --force
```

## Learn more

- [How to craft personal design tools with AI](https://pixelpoint.io/blog/how-to-craft-personal-design-tools-with-toolcraft/)
- [Toolcraft YouTube tutorial](https://youtu.be/-QlmkGZLzFo)

## License

Toolcraft is distributed under the [MIT License](./LICENSE.md), including the
CLI, bundled starter, runtime, and UI components. Generated applications retain
the MIT license and copyright notice.