inai-astro

CLI for the InAI Astro component library. Installs Astro components, blocks and templates from a private Git registry into your project — no runtime dependency, every file lives in your repo as code you can edit.

npx inai-astro init [email protected]:InAI-Team/inai-components-astro.git
npx inai-astro add button

• Public CLI on npm, private Git registry over SSH
• Zero npm runtime deps from the registry: init vendors @inai/tokens and @inai/astro-ui (lib + animations) as source into your project — you never pnpm add @inai/*
• Component source is copied into your project (not imported from node_modules); add rewrites every @inai/* import to a relative path pointing at the vendored runtime
• SHA-256 hashing of installed files for drift detection (status / diff / update)
• Resolves block → component and template → block dependencies automatically
• 23 OKLCH themes vendored at init time

Requirements

| Tool | Minimum | Notes | | ---- | ---------- | -------------------------------------------------- | | Node | 22 | enforced in package.json engines | | pnpm | 9 | or npm / yarn — the CLI is package-manager neutral | | git | modern | the CLI shells out to git clone over SSH | | SSH | configured | your key must be authorized for the registry repo |

The CLI never handles tokens. It inherits your system SSH config. Verify access before running:

ssh -T [email protected]   # expected: "Hi <user>!..."

Install

The CLI works best with npx so you always get the latest version:

npx inai-astro <command>

Or install globally:

npm i -g inai-astro
inai-astro <command>

Commands

init [repo-url]

Initialize a project. Three things happen:

1. Clones the registry into ~/.inai-astro/registry/ (override with INAI_CACHE_BASE).
2. Creates inai-astro.json at the project root with sensible defaults.
3. Vendors the runtime: copies packages/tokens/src/** → paths.tokens and packages/ui/src/{lib,animations}/** → paths.lib. After init you can import { setupGlobalAnimations } from '<paths.lib>' without installing any npm package.

npx inai-astro init [email protected]:InAI-Team/inai-components-astro.git

You will be prompted for a default theme. Re-run init to refresh the vendored runtime if the upstream library publishes new tokens or animations.

add [component]

Add a component, block or template — including its internal dependencies. Source .astro, .ts, .tsx, .js and .jsx files have their @inai/astro-ui and @inai/tokens imports rewritten on copy to relative paths against the consumer's paths.lib and paths.tokens, so the file works without any npm package install.

npx inai-astro add button                  # single item
npx inai-astro add button --dry-run        # preview file plan, no writes
npx inai-astro add button --force          # overwrite on conflict
npx inai-astro add --group creative        # everything in a group
npx inai-astro add --category block        # everything of a type
npx inai-astro add --all                   # full catalog

Flags:

| Flag | Purpose | | --------------------------- | ------------------------------------------ | | -a, --all | Install every registry item | | -g, --group <group> | creative | minimal | scroll | | -c, --category <category> | component | block | template | | -n, --dry-run | Print the copy plan without touching disk | | -f, --force | Overwrite existing files without prompting |

list

List all items available in the registry.

npx inai-astro list
npx inai-astro list --group scroll
npx inai-astro list --category block

status

Show installed items and their drift state (✓ ok, ! outdated, ? unknown) by comparing the SHA-256 hash stored at install time against the current registry hash.

npx inai-astro status

diff <component>

Show line-level differences between the locally installed file and the current registry version. Useful before running update on a file you've edited locally.

npx inai-astro diff button

update <component>

Pull the newest source for an installed item. Overwrites local edits — use diff first to inspect them.

npx inai-astro update button

sync

Fast-update the registry cache (git pull, falling back to re-clone if the cache is broken).

npx inai-astro sync

theme list

List the 23 OKLCH themes vendored from @inai/tokens.

npx inai-astro theme list

theme create

Scaffold a custom theme by copying a base.

npx inai-astro theme create --name brand --base jap

| Flag | Default | Purpose | | ------------------- | ------- | ---------------------- | | -n, --name <name> | — | Name for the new theme | | -b, --base <base> | inai | Existing theme to copy |

inai-astro.json reference

Created by init at your project root. All paths.* are editable — the CLI never enforces a specific structure, it just copies files there.

{
  "$schema": "https://inai-astro.dev/schema.json",
  "registrySource": "[email protected]:InAI-Team/inai-components-astro.git",
  "theme": "inai",
  "darkMode": true,
  "paths": {
    "components": "src/components/ui",
    "blocks": "src/blocks",
    "templates": "src/templates",
    "tokens": "src/styles/tokens",
    "lib": "src/lib",
  },
  "installed": {
    "button": {
      "version": "0.1.0",
      "group": "creative",
      "category": "component",
      "hash": "<sha-256>",
      "installedAt": "2026-05-12T10:00:00.000Z",
    },
  },
}

Cache

Registry source is cached under ~/.inai-astro/registry/ by default. Override with the INAI_CACHE_BASE environment variable:

INAI_CACHE_BASE=/tmp/inai npx inai-astro sync

The cache is a regular git working tree — you can inspect it like any clone.

SSH troubleshooting

| Symptom | Likely cause | Fix | | -------------------------------------- | ------------------------------------------ | -------------------------------------------------------------- | | Permission denied (publickey) | SSH key not authorized on the registry org | Add your key under your GitHub account; confirm org membership | | Host key verification failed | First-time SSH to the host | ssh-keyscan github.com >> ~/.ssh/known_hosts | | Registry not found / corrupted cache | Local cache broken | npx inai-astro sync (re-clones automatically if needed) | | fatal: unable to access ... HTTPS | URL uses HTTPS but expected SSH | Use the [email protected]:... form, not https:// | | Slow init on first run | Cold clone of the registry | Expected — subsequent commands reuse the cache |

If a command fails with no obvious cause, re-run it with --dry-run (where applicable) or inspect the cache directly at ~/.inai-astro/registry/.

Exit codes

The CLI returns:

| Code | Meaning | | ---- | --------------------------------------------------------- | | 0 | Success | | 1 | Unhandled error (git failure, missing registry, IO, etc.) |

Most failure modes log a chalked error message before exiting. Use --dry-run to validate plans without side effects.

Registry repo

The registry repo (InAI-Team/inai-components-astro) is private and accessed by SSH. The CLI never reads or stores credentials — your local ssh-agent / ~/.ssh/config is the source of truth.

If you need access:

1. Get added to the InAI-Team GitHub organization.
2. Ensure your SSH key is on your GitHub account.
3. Run ssh -T [email protected] to confirm.

Development

cd packages/cli
pnpm build           # compile TypeScript to dist/
pnpm test            # vitest, ~796 lines covering e2e + units
pnpm check-types     # tsc --noEmit
pnpm lint            # eslint src

prepublishOnly runs build + test automatically before npm publish.

License

MIT