akm-cli
Version:
akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur
248 lines (162 loc) • 13.3 kB
Markdown
title: 'akm 0.5.0: Wikis, Workflows, Vaults, and a Writable Stash'
cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
series: akm-releases
description: 'akm 0.5.0 ships multi-wiki support, workflow and vault asset types, writable git stash sync, and a one-off --trust install bypass.'
tags:
- ai
- agents
- cli
- release
published: true
date: '2026-04-24T05:18:44Z'
id: 3539588
> This is a dated article from AKM's publishing archive. For current product behavior, see the
> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
akm 0.5.0 is out. This release adds three new asset types — wikis, workflows, and vaults are now first-class citizens — plus writable git stash support so your stash can sync back to a remote. It also upgrades the self-update path to cover npm, bun, pnpm, and binary installs, and ships a new `akm help migrate` command for release-to-release guidance. There is one breaking change for anyone who was using the single-wiki LLM POC from 0.4.x.
## TL;DR
- `akm wiki create|register|list|show|remove|pages|search|stash|lint|ingest` — multi-wiki support, no LLM required
- `akm workflow template|create|start|next|complete|status|list|resume` — multi-step agent procedures in the stash
- `akm vault list|show|create|set|unset|load` — `.env`-backed secrets that never appear in structured output
- `akm add <source> --writable` + `akm save` — push your stash changes back to a remote git repo
- `akm add <source> --trust` — bypass the install audit for a single install
- `akm add --type wiki --name <name> <source>` / `akm wiki register` — register an existing directory or repo as a first-class wiki
- `akm upgrade` now covers npm, bun, pnpm, and standalone-binary installs
- `akm help migrate <version>` prints release notes and migration guidance for any shipped release
- **Breaking**: the single-wiki LLM POC is removed; migrate to `akm wiki …`
## Multi-wiki support
The biggest addition in 0.5.0 is a proper wiki asset type. A wiki is a structured knowledge base living at `<stashDir>/wikis/<name>/` with a defined layout: `schema.md` describes what goes in it, `index.md` is auto-generated by `akm index`, `log.md` tracks change history, `raw/` holds unprocessed source material, and the rest are agent-authored pages.
```sh
# Create a new wiki
akm wiki create architecture # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
# List all wikis
akm wiki list # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
# See what pages a wiki has
akm wiki pages architecture # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
# Search within a wiki
akm wiki search architecture "deployment" # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
# Lint a wiki for structural problems
akm wiki lint architecture # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
# Ingest raw content into raw/
akm wiki stash architecture ./notes/adr-001.md # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
# Print the ingest workflow for the wiki
akm wiki ingest architecture # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
```
Wiki pages are indexed by `akm index` and show up in stash-wide `akm search`, so you do not need to remember which wiki a page lives in. Raw sources under `raw/` plus the wiki root infrastructure files `schema.md`, `index.md`, and `log.md` are intentionally excluded from indexing and search results. Running `akm index` also regenerates each wiki's `index.md` as a side effect.
The design principle is **akm surfaces, the agent writes**. akm makes no LLM calls. It owns only the operations where correctness is structural and deterministic: lifecycle management, raw-slug uniqueness, lint checks, index regeneration. The agent owns page content. This keeps the CLI fast and predictable — a wiki command always completes in milliseconds, and you can run it in any environment without model configuration.
The 10-verb surface (`create`, `register`, `list`, `show`, `remove`, `pages`, `search`, `stash`, `lint`, `ingest`) covers the full lifecycle from creation to indexing to removal.
If you already have a wiki-shaped directory or repo you want to adopt without copying it, use `akm wiki register`:
```sh
# Register a local directory as a first-class wiki
akm wiki register notes ~/team/notes # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
# Or via the unified add command
akm add --type wiki --name notes ~/team/notes # doclint:ignore (historical — akm 0.5.0 release announcement; `--type` removed from `add` in the 0.9.0 bundle-adapter refactor)
# Registered external wikis show up in both `akm list` and `akm wiki list`
```
Registration refreshes source state and wiki search hits immediately, and the indexer normalizes external wiki refs on subsequent runs.
## Workflow asset type
Workflows are multi-step procedures stored in the stash. An agent running a complex process — a release checklist, an onboarding sequence, a debugging runbook — can use `akm workflow next` to step through it deterministically rather than relying on its context window to track state.
```sh
# Author a workflow
akm workflow create release-checklist
# Start an instance
akm workflow start workflow:release-checklist # doclint:ignore (historical 0.5.0 workflow lifecycle removed in 0.9)
# Advance to the next step
akm workflow next workflow:release-checklist # doclint:ignore (historical 0.5.0 workflow lifecycle removed in 0.9)
# Check where you are
akm workflow status workflow:release-checklist
# Mark a specific step done (defaults to --state completed)
akm workflow complete <run-id> --step validate --notes "Inputs verified" # doclint:ignore (historical 0.5.0 workflow lifecycle removed in 0.9)
# List all workflow runs
akm workflow list
# Print a starter workflow you can adapt
akm workflow template # doclint:ignore (historical — akm 0.5.0 release announcement; `template` folded into `workflow create --print` in the 0.9.0 CLI overhaul)
```
Workflows live in the stash like any other asset, so `akm search workflow:…` finds them and `akm show workflow:release-checklist` renders the current step. They can be shared in a stash and versioned in a git stash.
## Vault asset type
Vaults store secrets and environment configuration. Each vault is a `.env` file in the stash. The key constraint: vault values never appear in structured output. `akm show vault:<name>` and `akm vault list` display key names and metadata, but not the values themselves.
```sh
# List vaults
akm vault list # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
# Show keys in a vault (no values)
akm show vault:prod-secrets
# Create a new empty vault
akm vault create prod-secrets # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
# Set a key (three-positional form or combined KEY=VALUE form)
akm vault set vault:prod-secrets API_KEY abc123 # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
akm vault set vault:prod-secrets API_KEY=abc123 --comment "Rotate every 90 days" # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
# Remove a key
akm vault unset vault:prod-secrets API_KEY # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
# Print the vault file path for current-shell loading
source "$(akm vault path vault:prod-secrets)"
# Run one command with the vault injected
akm vault run vault:prod-secrets -- env # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
```
`akm vault path` is the current-shell loading path and `akm vault run` is the one-shot command execution path. Values never appear in structured output; `vault run` passes them directly to the child process environment.
This is a deliberate tradeoff: vaults are not a full secrets manager. They are a thin, auditable layer that keeps your `.env` files alongside your other agent assets and prevents accidental leakage through `akm show` or `akm search` results.
## Writable git stash and `akm save`
Until now, git-backed stashes were read-only: `akm add github:owner/repo` would clone the repo, but you could not push changes back. 0.5.0 changes that.
```sh
# Clone a git stash and opt it into push-on-save
akm add github:your-org/your-stash --writable # doclint:ignore (historical — pre-0.9.0 command spelling)
# Make some changes — add a skill, author a wiki page, record a memory
akm remember "Production DB is read-only on Sundays"
# Commit and push
akm save -m "add production DB note" # doclint:ignore (historical — akm 0.5.0 release announcement; `save` renamed `sync` in 0.9.0, `-m` survives as `sync`'s own alias)
```
If the stash has a remote configured and `--writable` was used on install, `akm save` runs `git commit` and `git push`. Without `--writable` (or without a remote), it commits locally only.
The default stash is now auto-initialized as a git repo on `akm setup`, so `akm save` works out of the box even before you wire up a remote.
The git stash provider also switches from HTTP tarball download to `git clone`, which means you get proper git history and the ability to `git pull` manually if you prefer.
## `--trust` flag for installs
akm 0.4.0 added a pre-install audit that scans stash contents for dangerous patterns. By default, installs from unrecognized sources require confirmation. For sources you know and trust, you can skip the audit entirely:
```sh
akm add github:your-org/internal-stash --trust # doclint:ignore (historical — akm 0.5.0 release announcement; `--trust` no longer a flag on current `add`)
```
`--trust` is a one-off bypass — it does not add the source to any persistent allowlist. Use it when you control the source and do not want to step through the audit prompt in a non-interactive context (a CI script, an automated agent workflow, a container build).
When a blocked install error occurs, the error message includes a `hint` field referencing `--trust` as a remediation option.
## Breaking change: single-wiki LLM POC removed
If you were using the wiki functionality introduced in 0.4.1, you will need to migrate. The following have been removed:
- `akm lint` command
- `akm import --llm` and `akm import --dry-run` flags
- `knowledge.pageKinds` config key
- The `ingestKnowledgeSource` and `lintKnowledge` LLM prompts
**Migration path:**
1. Create a wiki for your content: `akm wiki create <name>`
2. Move raw source files into `wikis/<name>/raw/`: `akm wiki stash <name> <file>`
3. Have your agent author wiki pages from the raw content
4. Run `akm index` to regenerate the wiki index
The new surface is more capable — 10 verbs vs the old 2, proper multi-wiki support, structural lint, and page search — and it does not require an LLM to be configured for any of the CLI operations.
## Broader `akm upgrade` coverage
`akm upgrade` used to assume a standalone-binary install. 0.5.0 detects how akm was installed (npm, bun, pnpm, or binary) and runs the right self-update path for each. The same command now works whether you bootstrapped from the install script or from a package manager, and the internal runtime-asset coverage was expanded so newly shipped asset types stay up to date after an upgrade.
```sh
akm upgrade # Works for binary, npm, bun, and pnpm installs
akm upgrade --check # Report whether an update is available, without installing
```
## `akm help migrate <version>` — release notes at the CLI
Release notes belong where you're actually working. `akm help migrate` prints the relevant CHANGELOG section plus embedded migration guidance for a given version, so you can review what changed (and what to do about it) without leaving the terminal.
```sh
akm help migrate 0.5.0 # or v0.5.0
akm help migrate latest # resolve against the most recent CHANGELOG entry
```
It favors the bundled CHANGELOG section when it exists and falls back to an embedded summary and a link to the full changelog otherwise.
## Upgrade
```sh
akm upgrade
```
Or reinstall from scratch:
```sh
curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash
```
Full changelog at [CHANGELOG.md](https://github.com/itlackey/akm/blob/main/.github/CHANGELOG.md).
> **Note (2026-04-23):** This post has been updated to align with akm 0.6.0 terminology. Earlier wording referred to a *kit* and the *Kit Maker's Guide*; those terms have been renamed to *stash* and *Stash Maker's Guide* throughout. The pre-rename text is preserved in this repository's git history.