cli-okf

Install OKF bundles into your project from npm, any git repository (GitHub / GitLab / SSH), or a local path — modeled on the way npx skills add installs skills.

An OKF bundle is any directory containing an OKF.md manifest (YAML front-matter + markdown), alongside whatever asset files the bundle ships.

Usage

No install required — run it with npx:

npx cli-okf add <source> [options]

Sources

| Spec | Resolves to | | --- | --- | | owner/repo | GitHub repository (shorthand) | | owner/repo#branch | …at a branch, tag, or commit | | owner/repo/path/to/bundle | …restricted to a sub-directory | | https://github.com/o/r/tree/main/x | GitHub tree URL (ref + subpath) | | https://gitlab.com/org/repo | GitLab repository | | [email protected]:owner/repo.git | any SSH git URL | | npm:@scope/[email protected] | npm package (npm: prefix optional) | | ./local/folder | a folder on disk |

Examples

# From a GitHub repo (searches ./okf, ./bundles, etc. for OKF.md)
npx cli-okf add vercel-labs/skills

# A single bundle in a sub-directory, at a branch
npx cli-okf add owner/repo/bundles/my-okf#main

# From npm, copying files instead of symlinking
npx cli-okf add npm:@acme/okf-starter --copy

# From a local folder, installed globally into ~/.okf
npx cli-okf add ./my-okf --global

# See what a source offers without installing
npx cli-okf add owner/repo --list

Commands

cli-okf add <source> [options]   Fetch a source and install its OKF bundles
cli-okf list [options]           List installed bundles in the current scope
cli-okf remove <name> [options]  Remove an installed bundle

Options

| Flag | Description | | --- | --- | | -s, --skill <name> | Only install the named bundle (repeatable) | | -g, --global | Install into ~/.okf instead of ./.okf | | --dir <path> | Install into an explicit directory | | --copy | Copy files instead of symlinking | | -l, --list | List bundles found in the source without installing | | -y, --yes | Overwrite existing bundles without asking | | -q, --quiet | Only print essential output | | -h, --help | Show help | | -v, --version | Print version |

How it works

1. Parse the source spec into a git URL, npm spec, or local path.
2. Fetch it: shallow git clone for git sources, npm pack + extract for npm, or read directly for local paths.
3. Discover bundles by finding directories that contain an OKF.md (well-known folders like okf/ and bundles/ are searched first, then a bounded recursive walk).
4. Install each bundle into the scope directory (./.okf/<name>), copying for remote sources and symlinking local ones so edits stay live.

The OKF.md manifest

---
name: my-okf
description: What this bundle provides
metadata:
  internal: false
---

# My OKF bundle

Markdown body / instructions / documentation for the bundle.

Only name and description are meaningful today; unknown front-matter keys are preserved under metadata. If name is omitted, the directory name is used.

Programmatic API

Everything the CLI does is exported for use in scripts:

import { add, list, remove, parseSource, findBundles } from "cli-okf";

const result = await add("owner/repo#main", { copy: true, only: ["my-okf"] });
console.log(result.installed); // [{ name, target, mode, overwritten }]

Requirements

• Node.js ≥ 18
• git on PATH for git sources
• npm on PATH for npm sources

Development

npm install
npm test          # vitest
npm run typecheck # tsc --noEmit
npm run build     # emit dist/ (ESM + CJS + bin + types)

License

MIT © Birat Datta