> ## Documentation Index
> Fetch the complete documentation index at: https://arkor-92aeef0e-eng-635.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# arkor init

> Scaffold an Arkor project in the current directory.

# `arkor init`

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm arkor init
  ```

  ```bash npm theme={null}
  npm arkor init
  ```

  ```bash yarn theme={null}
  yarn arkor init
  ```

  ```bash yarn-berry theme={null}
  yarn run arkor init
  ```

  ```bash bun theme={null}
  bun arkor init
  ```
</CodeGroup>

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](/quickstart#1-scaffold-a-project) runs the same scaffolder one directory up).

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.

## Synopsis

```
arkor init [options]
```

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

## 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 (`unsloth/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.

## 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:

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm arkor init --yes --template triage --use-pnpm --skip-git
  ```

  ```bash npm theme={null}
  npm arkor init --yes --template triage --use-npm --skip-git
  ```

  ```bash yarn theme={null}
  yarn arkor init --yes --template triage --use-yarn --skip-git
  ```

  ```bash yarn-berry theme={null}
  yarn run arkor init --yes --template triage --use-yarn --skip-git
  ```

  ```bash bun theme={null}
  bun arkor init --yes --template triage --use-bun --skip-git
  ```
</CodeGroup>

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

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

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm arkor init
  ```

  ```bash npm theme={null}
  npm arkor init
  ```

  ```bash yarn theme={null}
  yarn arkor init
  ```

  ```bash yarn-berry theme={null}
  yarn run arkor init
  ```

  ```bash bun theme={null}
  bun arkor init
  ```
</CodeGroup>

Accept defaults, skip install, skip git:

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm arkor init --yes --skip-install --skip-git
  ```

  ```bash npm theme={null}
  npm arkor init --yes --skip-install --skip-git
  ```

  ```bash yarn theme={null}
  yarn arkor init --yes --skip-install --skip-git
  ```

  ```bash yarn-berry theme={null}
  yarn run arkor init --yes --skip-install --skip-git
  ```

  ```bash bun theme={null}
  bun arkor init --yes --skip-install --skip-git
  ```
</CodeGroup>

Pin the template and force the package manager:

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm arkor init --template translate --use-pnpm
  ```

  ```bash npm theme={null}
  npm arkor init --template translate --use-npm
  ```

  ```bash yarn theme={null}
  yarn arkor init --template translate --use-yarn
  ```

  ```bash yarn-berry theme={null}
  yarn run arkor init --template translate --use-yarn
  ```

  ```bash bun theme={null}
  bun arkor init --template translate --use-bun
  ```
</CodeGroup>

## 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](/concepts/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.