standardembed

README

eka-cli

eka-cli is the official command-line interface for the EKA engineering knowledge standard. It is a consumer of eka-core — the CLI contains no domain logic of its own; every command delegates to an eka-core engine. It is the official interface for bootstrapping, validating, exchanging, and running the EKA Knowledge Runtime.

Module path: github.com/maleolabs/eka-cli · CLI v1.10.0 · EKA Standard 1.1 · eka-core v1.7.0

Highlights (v1.7 — v1.10)

Restored from 3355ebe — README.md was emptied in cb6b6ab (hollow-gap marker, 183 deletions) and left 0 bytes since 2026-08-28.

Code Context, Discovery & Indexing (v1.9, eka-core/codegraph) — deterministic local source indexing without embeddings:

• eka code-context [query] --depth local|dependency|engineering --level 0..3 --limit 1..64 — bounded context: level 0 inventory, 1 symbols, 2 imports, 3 source content. Cache ~/.cache/eka/codegraph/<sha256(root)[:16]>.json, atomic tmp+rename, fingerprint sha256(path␀language␀digest␀size). Invalidation by Root+Digest comparison, safe to delete.
• eka code-discover <query> [--scope <path>] --limit 1..64 — natural-language tokenized (lower, -_/. → space), scored by path + go/ast symbols (function|type|value, import refs), reason + normalized confidence, fallback inventory when no match (provenance confidence 0.1).
• eka code-get <path> — exact retrieval with traversal guard (.. rejected), returns Unit{content} + per-file symbols/refs, sorted deterministically.
• Go-aware (go/parser + ast.Inspect), others remain language: unsupported inventory entries. Skips .git/vendor/node_modules. Response schema eka/code-context/1, eka/code-discover/1, eka/code-get/1 with indexDigest + provenance{source:local-index, method:deterministic-*}.
• See research-LLM-context-efficiency.md §3 — code was out-of-graph (raw read/grep), now bounded/deterministic instead of dump.

Universal Capture Gateway (v1.10, ADR-035 v3, spec provenance-capture:1):

• eka capture --reconcile --from-git — reads git diff --cached + git log --since=24h, heuristic classifier (file-type + commit verbs), scaffolds draft with provenance=reconciled, sourceCommitSha, confidence, captureMeta{classifier: git-heuristic v1, dedupeKey: hash(title)}.
• Dedupe: exact dedupeKey or similarity >=0.6 (capture.threshold) within capture.dedupeWindow (default 24h, eka.yaml) reuses draft — new capture becomes cmt:note discusses target.
• eka capture --dry-run preview, --install-hooks standalone.

Layer-2 Git Hooks via Anvil (anvil.yaml lifecycle.platform_sync):

• scripts/platform-sync.sh symlinks eka-standard/templates/hooks (pre-commit, pre-push) → .git/hooks. Runs on anvil deployment install / anvil server release activate, idempotent, never blocks deployment. Fallback inline hooks when templates missing.
• Manual: eka capture --install-hooks or sh scripts/platform-sync.sh.

Other additions since last README: assign / reassign / unassign (single-assignee work-item), relate (add edges without re-publish), code-context parity + bounds tests.

Installation

Release binaries (recommended)

Prebuilt binaries for Linux and macOS (amd64, arm64) are published on the GitHub releases page. The installers download the binary, verify its SHA-256 checksum against the release's SHA256SUMS.txt (fail-closed — an unverifiable binary is never installed), and place it on your PATH.

Linux / macOS:

curl -fsSL https://github.com/maleolabs/eka-cli/releases/latest/download/install.sh | sh

Windows (PowerShell):

Invoke-RestMethod https://github.com/maleolabs/eka-cli/releases/latest/download/install.ps1 | Invoke-Expression

Options (install.sh): --version vX.Y.Z, --to <dir>, --completion <shell>, --no-completion.

From source

go install github.com/maleolabs/eka-cli/cmd/eka@v1.10.0

Basic usage

The complete command list, with one-line descriptions:

Command	Description
validate	Validate an EKA repository against the conformance rules.
init	Bootstrap a new EKA repository.
export	Export an EKA repository to an RSF package.
import	Import an RSF package into the current repository.
get	Retrieve knowledge as machine-readable CKO JSON.
context	Construct the engineering context around a knowledge subject.
view	Project the Engineering Knowledge Model.
watch	Watch a projection live, redrawn on change.
sync	Sync a repository with the EKA workspace.
project	Manage EKA workspace projects.
status	Show the EKA workspace status.
integrity	Verify the EKA workspace integrity.
update	Update the EKA CLI to the latest release.
version	Print version information.
transition	Transition a work item, plan or container state.
note	Create a note draft (comment) on an artifact.
feedback	Report EKA feedback (draft → publish as a GitHub issue).
snapshot	Inspect and repair repository snapshots.
new	Scaffold a draft.
edit	Open a draft in the editor.
draft	Manage drafts (list / validate).
publish	Publish a draft as an immutable knowledge object.
discard	Discard a draft without publishing.
assign	Assign a work item to a member.
reassign	Move a work item's assignment to another member.
unassign	Remove a work item's assignment.
relate	Add relationship edges without re-publishing.
capture	Universal capture gateway (provenance=reconciled from git, ADR-035).
code-context	Serve deterministic local code context (level 0..3, depth local/dependency/engineering).
code-discover	Discover code candidates deterministically (query/scope → reason/confidence).
code-get	Retrieve exact file content deterministically.

Get help for any command with eka help <command> or eka <command> --help.

Exit codes are deterministic: 0 fully compliant (warnings allowed), 1 blocking violations present, 2 usage or internal error.

Code context quickstart

# inventory only
eka code-context --level 0 --limit 5
# search + rank
eka code-discover "auth middleware" --limit 5
# focused context with imports
eka code-context "codegraph" --depth dependency --level 2
# exact file
eka code-get cmd/code_context.go

Capture quickstart

# install hooks (also via anvil platform_sync)
eka capture --install-hooks

# stage changes then reconcile
git add -A
eka capture --reconcile --from-git
eka capture --reconcile --from-git --dry-run  # preview

Hooks read staged diff + recent log, scaffold provenance=reconciled drafts, dedup within capture.dedupeWindow — duplicates become notes.

Plugins

eka-cli is extensible through an executable plugin contract (v1). A plugin extends the CLI — for example, eka-mcp adds AI-agent integration — without the CLI depending on any plugin's implementation.

Installing the official mcp plugin

eka plugin install mcp

This installs the official eka-mcp plugin from its GitHub release, with checksum verification (the plugin binary and its SHA256SUMS.txt always come from the same release; a missing or mismatched checksum refuses the install). The intended flow:

1. eka resolves the plugin identity mcp against the official registry.
2. The plugin binary is downloaded and checksum-verified, then placed on PATH (or ~/.eka/plugins) as eka-mcp.
3. eka runs eka-mcp manifest --json to learn what the plugin provides, and eka-mcp install <kind> --dir <dir> --json to delegate artifact installation (skills, commands) into the agent configuration directory.

Creating a plugin acceptable to eka-cli

A plugin is an executable named eka-<name> (e.g. eka-mcp) discoverable on PATH or under the EKA plugin directory ($EKA_PLUGIN_DIR, then ~/.eka/plugins). The CLI talks to it through two machine-readable subcommands; the JSON output on stdout is the contract.

1. eka-<name> manifest --json — emit the plugin self-description:

{
  "contract": "v1",
  "name": "mcp",
  "version": "0.1.0",
  "description": "one-line summary",
  "artifacts": [
    { "kind": "skills", "entries": ["eka-orientation", "…"] },
    { "kind": "commands", "entries": ["eka-discuss.md", "…"] }
  ]
}

The Manifest fields are contract (must equal "v1"), name, version (semver), description, and artifacts (the installable families, each with a kind and its entries).

2. eka-<name> install <kind> --dir <dir> [--dry-run] --json — install one artifact family into an agent configuration directory and emit the result:

{ "installed": ["eka-orientation", "…"], "version": "0.1.0" }

With --dry-run the plugin reports the plan without touching the filesystem.

Discovery. Discover finds any eka-* executable on PATH (excluding the CLI itself) plus any eka-* executable in the plugin directories; duplicate names collapse to the first discovered path.

Trust tiers. Plugins from the official registry (the curated set of maleolabs-published plugins, e.g. mcp) receive full trust and install with checksum verification, no interactive prompt. Third-party plugins require explicit consent before they are installed or executed — the user must approve the plugin before the CLI will act on it.

Plugins import the contract types from github.com/maleolabs/eka-core/plugin (Manifest, Artifact, InstallOptions, InstallResult, ContractVersion) to implement their executable side; they never import the CLI's internal packages.

Versioning

• Semantic versioning, tag-driven. The CLI build version defaults to dev and is overridden at build time:

  go build -ldflags "-X github.com/maleolabs/eka-cli/cmd.version=v1.2.3" ./cmd/eka
  

• eka version prints the CLI build version and the EKA standard version this CLI implements — EKA Standard 1.1 (RSF 2, Exchange 1, eka-cko-v2). The standard's two-component version axis is independent of the CLI's semver.

• Release pipeline — tag vMAJOR.MINOR.PATCH (RC suffix allowed, e.g. v1.2.3-rc.1) triggers .github/workflows/release.yml: semver regex check, gh release view duplicate guard, anvil pipeline ci quality gate (gofmt/vet/test) before publication, and gh release create --generate-notes. See CONTRIBUTING.md for the full release process, tag-immutability rule (pushed tags are never deleted/recreated), and ecosystem release order eka-standard -> eka-core -> eka-cli -> eka-mcp.

Contributing

See CONTRIBUTING.md. Design records and ADRs live in the EKA knowledge system, not in this repository.

License

Apache License 2.0.

Documentation

Overview

Package hooksembed embeds the Layer-2 git hook templates into the binary so `eka capture --install-hooks` works without external paths.

The files are vendored from eka-standard/templates/hooks (pre-commit, pre-push) into eka-cli/templates/hooks and embedded at compile time. This makes the release binary standalone and offline: no /home/... absolute paths, no sibling checkout required. Anvil/dev mode still prefers a real file on disk (symlink) when it exists; the embedded bytes are the fallback for release installs.

Embedding pattern mirrors standardembed.go (ADR-023): a root-level package with //go:embed over the module root. This file shares the standardembed package (same directory) to satisfy Go's one-package-per-directory rule.

Package standardembed embeds the EKA standard declaration file (the root `EKA` compact consumer summary) into the binary and exposes it to the rest of the codebase.

The file is vendored from the eka-standard release asset (github.com/maleolabs/eka-standard, releases/download/v1.0/EKA) and is the single canonical copy the CLI distributes: the bootstrap engine writes its bytes into every generated repository, and the CLI's reported standard version is derived from its `Version X.Y` line — never from a hardcoded constant.

Embedding is the ADR-023 distribution pattern (a root-level package with //go:embed over the module root): the binary stays standalone and offline — `eka init` never fetches anything — and dry-run stays deterministic because the content is a compile-time resource.

The build-time version-consistency test (standardembed_test.go) locks the embedded `Version X.Y` line to the standard version the CLI conformance rules implement (exchange.SpecificationVersion).

Index

• Variables
• func Declaration() []byte
• func HookBytes() map[string][]byte
• func Hooks() map[string][]byte
• func MustVersion() string
• func Version() (string, error)

Variables

var PreCommit []byte

var PrePush []byte

Functions

func Declaration

func Declaration() []byte

Declaration returns the embedded EKA standard declaration file bytes. The returned slice is the exact content written into generated repositories (deterministic: identical bytes on every run and every build of the same source tree).

func HookBytes

func HookBytes() map[string][]byte

HookBytes is an alias for Hooks for discoverability.

func Hooks

func Hooks() map[string][]byte

Hooks returns the embedded hook templates keyed by hook name. The map is a fresh allocation on each call so callers may not mutate the underlying embedded bytes.

func MustVersion

func MustVersion() string

MustVersion returns Version(), panicking when the embedded declaration does not carry a valid `Version X.Y` line. It is used for values that are structurally fixed at build time: a missing version line is a broken vendored asset and must fail loudly rather than silently report a wrong standard version.

func Version

func Version() (string, error)

Version parses the `Version X.Y` line of the embedded declaration and returns the version value (e.g. "1.0"). The parse is anchored to the file shape: line 1 must be the EKA STANDARD header and line 2 the Version X.Y line — any other shape is rejected deterministically. The embedded file is a compile-time resource, so a failure here means the vendored asset is broken and the binary must not claim a version.