# akm CLI

You have access to a searchable library of scripts, skills, commands, agents, knowledge documents, workflows, env files, secrets, lessons, and memories via `akm`. Search your sources first before writing something from scratch.

## Agent Task Loop

For any task, follow this loop:
1. `akm curate "<task>"` — find the best matching asset
2. `akm show <ref>` — read the schema (field names and structure)
3. Edit the workspace file using schema field names + task-specific values from your README
4. `akm feedback <ref> --positive` — record success; use `--negative --reason "..."` when it fails

For workflow tasks:
1. `akm show workflows/<name>` — inspect the procedure before executing it
2. `akm workflow run workflows/<name> --param_name=value` — execute every step and verification gate
3. `akm workflow status <run-id> --units` — inspect a stopped or failed run

Workflow runs are scoped to your current project/worktree/directory. Ref-based
commands like `workflow run workflows/<name>`, `workflow status workflows/<name>`,
and `workflow list` operate within the current scope only.

## Quick Reference

```sh
akm search "<query>"                          # Search all sources
akm curate "<task>"                          # Curate the best matches for a task
akm search "<query>" --type workflow          # Filter to workflow assets
akm search "memories/projectA/"               # List a subtree (conceptId prefix; trailing slash required)
akm search "<query>" --from all               # Also search registries
akm show <ref>                                # View asset details
akm help <command>                            # Show a command's options and subcommands
akm workflow run <ref>                        # Start or resume and execute a workflow
akm remember "Deployment needs VPN access"    # Record a memory in your bundle
akm remember "note" --bundle my-bundle         # Route write to a named writable bundle source
akm remember "note" --xref knowledge/auth-flow # Cite provenance in frontmatter xrefs (repeatable)
akm remember "fix" --supersedes memories/old-note # Write a correction AND demote the superseded asset
akm import ./notes/release-checklist.md       # Import a knowledge doc into your bundle
akm import ./doc.md --target my-bundle         # Route import to a named writable bundle source
akm proposal diff skills/akm-dream            # Diff proposal by ref, UUID, or 8-char prefix
akm proposal accept 7c115132                  # Accept by UUID prefix
akm proposal reject skills/my-skill --reason "..."  # Reject by ref
akm feedback <ref> --positive|--negative      # Record whether an asset helped
akm bundle add <ref>                                 # Add a source (npm, GitHub, git, local dir)
akm clone <ref>                               # Copy an asset to the working bundle (optional --dest arg to clone to specific location)
akm sync                                      # Commit (and push if writable remote) changes in the primary bundle (--no-push to commit only)
akm improve --no-sync                         # Run improve without the end-of-run auto-commit
akm improve --no-push                         # Auto-commit but skip push for this run
akm search "<query>" --from registry          # Search all registries (registry search was folded into search)
```

## Primary Asset Types

| Type | What `akm show` returns |
| --- | --- |
| script | A `run` command you can execute directly |
| skill | Instructions to follow (read the full content) |
| command | A prompt template with placeholders to fill in |
| agent | A system prompt with model and tool hints |
| knowledge | A reference doc (append `#<heading-slug>` to the ref to read one section) |
| workflow | Parsed steps plus workflow-specific execution commands |
| memory | Recalled context (read the content for background information) |
| env | A `.env` file of configuration an app loads together (many vars; sensitive or not — all protected); key names only. Inject with `akm env run <ref> -- <cmd>` (the agent-safe path — values stay on disk). |
| secret | A single sensitive value for AUTHENTICATION (token, key, cert); name only. Inject with `akm secret run <ref> <VAR> -- <cmd>`. |
| lesson | A distilled feedback lesson: `content` plus `action` (rendered from the `when_to_use` frontmatter). Read both before applying a related skill. Generated by the improve pipeline and promoted through the proposal queue. |

When an asset meaningfully helps or fails, record that with `akm feedback` so
future search ranking can learn from real usage.

## Error Shapes and Exit Codes

Every command returns JSON by default. On failure, the shape is always
emitted on **stderr** (stdout is normally left empty):

```json
{"ok": false, "error": "<message>", "code": "<optional machine-readable code>", "hint": "<optional remediation hint>"}
```

Exit codes:

| Code | Meaning |
| --- | --- |
| 0 | Success |
| 1 | Not found or command-reported failure |
| 2 | Usage / bad input |
| 4 | Health warning (`akm health` only) |
| 70 | Internal / unclassified error |
| 78 | Configuration error |

Check `ok === false` or a non-zero exit code to detect failure. The `hint`
field, when present, describes a corrective action. `search`/`curate`
success results also carry an additive `tip` field (a plain-text suggestion)
when the result set is empty.

`env run`, `secret run`, and `migrate` preserve the spawned process's exact
status. `task run` preserves configuration failures as exit 78; other failed
task results and failed `agent` dispatches map to exit 1 while retaining the
child status in their result envelope.

`akm lint` is the exception: it exits **0 on every successful run regardless
of findings**. Read `summary.flagged` to detect issues, or pass
`--fail-on-flagged` to opt into "exit 1 when findings exist":

```sh
akm lint | jq '.summary.flagged'              # always exit 0; read the count
akm lint --fail-on-flagged && deploy          # exit 1 if any flagged issues
```

## Proposals & improvement (0.8.0+)

`akm` ships a proposal queue so reflective edits, new asset drafts, and
feedback-distilled lessons land out-of-band before they touch the live
bundle. None of these commands mutate bundle content directly — they always
go through `akm proposal accept`.

```sh
akm improve <ref>                              # Produce an improvement proposal for an existing asset
akm improve <ref> --task "tighten the description"
akm proposal new <type> <name> --task "..."    # Draft a new asset proposal from a description
akm proposal new lesson docker-cleanup --task "consolidate cleanup feedback"
akm proposal list                              # List pending proposals
akm proposal list --status pending|accepted|rejected|reverted
akm proposal show <id>                          # Render the proposal body
akm proposal diff <ref-or-id>                   # Diff by ref, UUID, or 8-char prefix
akm proposal accept 7c115132                    # Accept by UUID prefix
akm proposal reject skills/my-skill --reason "not ready" # Reject by asset ref
akm search "<query>" --include-proposed        # Surface proposal-queue entries in search
```

Run `akm help <command>` for that command's options and subcommands. Run
`akm --help` for the command overview or `akm hints --detail full` for the
complete agent guide.