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

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 Toolcraft Designer License in `LICENSE.md`.
Designer client work is permitted under that license. Using AI coding assistants
or agents such as Codex, Claude, ChatGPT, Cursor, or similar tools to work on
generated apps is permitted. Platform, generator, AI software product,
app-builder, website-builder, template-marketplace, and resale uses require a
separate commercial license from Pixel Point.