Projects & indexing

A project is any directory registered with orkai. Developers index repos; researchers and analysts index folders of PDFs, CSVs, and notes — the same commands apply.

orkai init

Run once inside a folder. Creates a category in the daemon and writes .orkai.yaml in that directory.

cd /path/to/your/folder
orkai init

Requires a running daemon. Re-running on an already-initialized folder prints the existing config.

orkai index

Index the current directory (or a path). Settings load from .orkai.yaml; mode subcommands and flags override the file.

orkai index .                 # default: all (code + documents + analytics)
orkai index all .             # same as above, explicit
orkai index code .            # source code and text-code only
orkai index document .        # documents only (.md, .pdf, .docx, …)
orkai index analytics .       # spreadsheets only (.csv, .xlsx, .parquet)
orkai index --stats .         # show index state, do not index
orkai index --dry-run all .   # preview a full index

Index modes

Mode	What gets indexed
`all` (default)	Code + documents + analytics datasets (when `index.analytics.enabled`)
`code`	Tree-sitter symbols and text-code files only
`document`	Documents only
`analytics`	Tabular datasets only — see Spreadsheets & data

Legacy flags --document and --all still work but are deprecated in favor of orkai index document and orkai index all.

Common flags

Flag	Description
`--type code\|document\|analytics\|all`	Override mode (prefer subcommands)
`--lang go,python,…`	Filter code languages
`--exclude pat1,pat2`	Extra exclude globs beyond .gitignore
`--reset`	Delete indexed entities and re-index from scratch
`--no-clean`	Skip stale-entity cleanup after index
`--stats`	Print index statistics only
`--text-code-ext .proto`	Add extensions indexed as text-code
`--text-code-file Justfile`	Add exact filenames indexed as text-code

Built-in text-code includes json, yaml, sql, sh, css, Makefile, Dockerfile, go.mod, and more.

Index from a URL

Index a skill, standard, or document from the web — including GitHub tree URLs:

orkai index --url https://example.com/skill/SKILL.md \
  --name "My Skill" --category skills

orkai index --url https://github.com/org/repo/tree/main/skills/my-skill \
  --parent-file SKILL.md --name "My Skill" --entity-type skill --category skills

Use --parent-url or --parent-id to attach indexed URLs as children of an existing entity. GitHub blob URLs are converted to raw content automatically.

orkai unindex

Remove an indexed project and all its entities from the daemon.

orkai unindex my-project
orkai unindex d5a003d1f642f03946ac5f3798e77569

Accepts category name or ID. Run from any directory.

Annotations only

When annotations are enabled in daemon config, re-run the annotation pipeline without a full re-index:

orkai index --annotations-only .

Requires an existing project index. For what annotations, @orkai tags, and enriched source mean, see Knowledge layer.

.orkai.yaml

After the first index, orkai may persist resolved settings in .orkai.yaml. CLI mode subcommands and flags always win over the file. Default mode is index.type: all on new projects (orkai init).

index:
  type: all          # default for bare orkai index
  path: .
  analytics:
    enabled: true     # indexed by all or analytics mode

See orkai help index for the full schema.