arkor init

Scaffold an Arkor project in the current directory.

arkor init

Scaffolds src/arkor/index.ts, src/arkor/trainer.ts, arkor.config.ts, and a starter package.json in the current directory. Use this when you want to add Arkor to an existing repo (the Quickstart scaffolding flow runs the same scaffolder one directory up).

Synopsis

arkor init [options]

pnpm

pnpm arkor init

Options

Flag	Description
-y, --yes	Accept defaults instead of prompting (project name from the directory name, template triage).
--name <name>	Project name. Defaults to the current directory’s name (arkor-project if the path has no basename, e.g. /). The value is sanitised before it lands in package.json.
--template <id>	Starter template. Options: triage, translate, redaction. Unknown ids throw before any filesystem work.
--skip-install	Skip running the package manager’s install step after scaffolding.
--use-npm	Force npm as the package manager.
--use-pnpm	Force pnpm as the package manager.
--use-yarn	Force yarn as the package manager.
--use-bun	Force bun as the package manager.
--git	Initialise a git repo and create an initial commit, without asking.
--skip-git	Skip git init silently.

--git and --skip-git are mutually exclusive; passing both throws.

Behavior

Default flow

By default, the command is partly interactive: it prompts for a project name, a starter template, and (when not in a git repo) whether to run git init, and only then starts the package manager’s install step (no confirmation prompt) unless --skip-install is set. The git init confirmation is surfaced before install so you can answer every prompt upfront and walk away while install runs unattended; the actual git init + initial commit still execute after install so the generated lockfile lands in the initial commit. If no package manager can be resolved (no --use-* flag and detection from npm_config_user_agent fails), the install step is skipped and the outro prints a manual install hint.

Templates

Template	Task	Output shape
triage	Support triage	{ category, urgency, summary, nextAction }
translate	9-language translation	{ translation, detectedLanguage }
redaction	PII redaction	{ redactedText, redactedCount, tags }

All three pair the same small open-weight base (gemma-4-E4B-it) with a curated public dataset on HuggingFace.

Package manager detection

When no --use-* flag is passed, the CLI inspects npm_config_user_agent to detect the package manager that invoked it (this is the standard mechanism corepack uses, so pnpm dlx, yarn dlx, bunx, etc. all work).

If detection fails and no flag is passed, the install step is skipped and the outro prints a manual install hint.

Git policy

arkor init decides whether to run git init + initial commit by walking these rules in order:

1. If the current directory is already inside a git repo, skip (and log it).
2. If --skip-git is passed, skip.
3. If --git or -y is passed, run without asking.
4. In an interactive shell, prompt (default: yes).
5. In a non-interactive shell with no flag, skip.

The interactive confirmation is shown before install (so you don’t sit at a prompt after a multi-minute <pm> install), but git init execution still runs after install so the lockfile generated by the package manager is part of the initial commit. If commit signing fails (e.g. GPG agent isn’t running), the CLI falls back to an unsigned commit and warns; you can re-sign with git commit --amend -S later.

CI / non-interactive shells

When process.stdout is not a TTY, or CI is set in the environment, arkor init is non-interactive: prompts skip with their default values and never block waiting for input. To get a deterministic scaffold from CI:

pnpm

pnpm arkor init --yes --template triage --use-pnpm --skip-git

--yes accepts the project-name and template defaults (the directory’s basename and triage), --use-pnpm (or the matching --use-<pm>) short-circuits package-manager detection, and --skip-git opts out of git init. Pass --skip-install as well if your CI image already has node_modules/.

If you forget --yes in a non-interactive shell, the command still completes (prompts use their defaults) but the experience is silent and easy to miss in logs. Prefer the explicit form above.

Errors

Message	What it means	Fix
Pick one of --git / --skip-git, not both.	Both git flags were passed.	Pass at most one.
Unknown template "<id>". Available: triage, translate, redaction	--template value did not match any registered template id.	Use one of the listed ids.
Commit signing failed — created an unsigned commit.	git init succeeded but the initial commit could not be GPG-signed.	Re-sign with git commit --amend -S once your signing setup is fixed. The repo is otherwise fine.

Examples

Interactive:

pnpm

pnpm arkor init

Accept defaults, skip install, skip git:

pnpm

pnpm arkor init --yes --skip-install --skip-git

Pin the template and force the package manager:

pnpm

pnpm arkor init --template translate --use-pnpm

What gets written

The scaffolder touches six paths. None of them overwrites existing user content:

Path	Behavior
src/arkor/index.ts	Created with createArkor({ trainer }) if missing. Kept untouched if the file already exists.
src/arkor/trainer.ts	Created with the chosen template’s createTrainer({...}) if missing. Kept untouched if it exists.
arkor.config.ts	Created as a placeholder export if missing. Kept untouched if it exists. See Project structure.
README.md	Created with a starter README if missing. Kept untouched if it exists.
.gitignore	Created with node_modules/, dist/, .arkor/ if missing. Patched by appending .arkor/ if the file exists but does not already list it. Ok (no change) if .arkor/ is already there.
package.json	Created with name / private / type: "module" / starter dev+build+start scripts / devDependencies.arkor if missing. Patched to add any of those scripts that are absent and to add arkor under devDependencies if absent; existing values (e.g. a custom dev script) are not overwritten. Ok (no change) if everything is already in place.

The CLI prints the file list as a “Files” note before installing, with an action (created / kept / patched / ok) per path so you can see exactly what changed.

See also

• Quickstart for the greenfield scaffolding flow
• Project structure for what each generated file is for
• arkor dev for the next step after init