Documentation Index
Fetch the complete documentation index at: https://docs.arkor.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 pnpm create arkor my-app flow runs the same scaffolder one directory up).
By default, the command is partly interactive: it prompts for a project name and a starter template, then runs the package manager’s install step automatically (no confirmation prompt) unless --skip-install is set, and prompts before running git init. 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.
Synopsis
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. Visible options: triage, translate, redaction. The validator also accepts hidden ids (minimal, alpaca, chatml) when passed explicitly. 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.
Templates
| Template | Task | Output shape |
|---|
triage | Support triage | { category, urgency, summary, nextAction } |
translate | 9-language translation | { translation, detectedLanguage } |
redaction | PII redaction | { redactedText, redactedCount, tags } |
unsloth/gemma-4-E4B-it) with a curated public dataset on HuggingFace.
The hidden templates (minimal, alpaca, chatml) are intentionally bare and exist as references. They do not appear in the interactive picker.
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:
- If the current directory is already inside a git repo, skip (and log it).
- If
--skip-git is passed, skip.
- If
--git or -y is passed, run without asking.
- In an interactive shell, prompt (default: yes).
- In a non-interactive shell with no flag, skip.
Git init 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.
In 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:
npx 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 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.
Common 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, minimal, alpaca, chatml | --template value did not match any registered template id. | Use one of the listed ids. The hidden ids (minimal, alpaca, chatml) only work when passed explicitly. |
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:
Accept defaults, skip install, skip git:
npx arkor init --yes --skip-install --skip-git
npx 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. |
action (created / kept / patched / ok) per path so you can see exactly what changed.
