Skip to content

getting-started.md

Latest commit

 

History

History
221 lines (159 loc) · 7.2 KB

getting-started.md

File metadata and controls

221 lines (159 loc) · 7.2 KB
Raw

Getting Started

This guide walks you through installing akm, adding your first asset, and using search and show to discover capabilities.

Runtime Requirement

AKM 0.8 requires the Bun runtime or the prebuilt binary. Node.js is not supported in this release. Cross-runtime compatibility is planned for 0.9.0.

Install

Option 1 — Prebuilt binary (no runtime required):

# Linux / macOS
curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash

# Windows (PowerShell)
irm https://github.com/itlackey/akm/releases/latest/download/install.ps1 | iex

Or download a standalone binary directly from the GitHub releases page.

Option 2 — Bun (requires Bun >= 1.0):

bun install -g akm-cli

Windows installation notes

install.ps1 requires Windows PowerShell 5.1 or newer (default on Windows 10 and Windows 11). If you see a SmartScreen prompt or an ExecutionPolicy error when running irm ... | iex, do one of:

# Allow scripts in this session only, then re-run the install:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
irm https://github.com/itlackey/akm/releases/latest/download/install.ps1 | iex
# Or download the script, unblock the file, and run it:
Invoke-WebRequest -Uri https://github.com/itlackey/akm/releases/latest/download/install.ps1 -OutFile install.ps1
Unblock-File .\install.ps1
.\install.ps1

Windows ARM64 hosts install the x64 binary, which Windows runs via x86_64 emulation. Native ARM64 support is tracked alongside Bun's ARM64-on-Windows progress.

First-Time Setup

For a guided first run, start with:

akm setup

akm setup walks through stash location, embedding/LLM settings, semantic search asset preparation, registries, and sources, then saves your config, initializes the stash directory, and builds the search index.

Initialize Your Working Stash

For non-interactive use, run akm setup --yes to create your working stash — the primary directory where your personal assets live:

akm setup --yes
akm setup --dir ~/custom-stash

This creates ~/akm with subdirectories for each asset type: scripts/, skills/, commands/, agents/, knowledge/, workflows/, memories/, env/, secrets/, wikis/, and lessons/. See technical/filesystem.md for platform-specific paths and environment variable overrides.

Add Your First Asset

Create a simple shell script in the scripts/ directory:

cat > ~/akm/scripts/hello.sh << 'EOF'
#!/usr/bin/env bash
# A simple greeting script
echo "Hello from akm!"
EOF
chmod +x ~/akm/scripts/hello.sh

Any file with a known extension (.sh, .ts, .py, etc.) placed in your working stash is automatically recognized. The scripts/ directory is not required -- it just increases classification confidence. See concepts.md for how classification works.

Prefer inline metadata over .stash.json sidecars: .stash.json support was removed in v0.8.0. Markdown assets should use frontmatter, and scripts should use structured header comments such as a short leading description, @param, and execution hints like @run / @setup / @cwd when needed.

Index

Build the search index so your assets are discoverable:

akm index

setup vs index: akm setup creates your working stash directory (run once). akm index scans all sources, then builds the search database (run whenever you add or change assets). They are separate steps — setup creates the stash, index makes its contents searchable.

Run akm index --full to force a complete rebuild instead of an incremental update. If a workflow file is malformed, akm now skips that asset, continues indexing the rest of the stash, and reports the skipped file in warnings.

Search

Find assets by keyword:

akm search "hello"

Results include a ref field (for example script:hello.sh) that you pass directly to akm show. Filter by type or limit results:

akm search "deploy" --type script --limit 5

See cli.md for the full set of search flags.

Show

Inspect an asset by its ref:

akm show script:hello.sh

The output is structured JSON containing everything an agent needs to use the asset. For scripts, this includes a run command plus optional cwd and setup. For agents, a prompt payload. For knowledge, navigable content with view modes.

See technical/show-response.md for the full per-type field reference.

Add Sources

Add any source — a local directory, a GitHub repo, an npm package, or a website. Every source materialises files to a directory; akm indexes them locally:

akm add ~/.claude/skills              # Your Claude Code skills
akm add github:owner/repo             # A team's shared stash
akm add @scope/my-stash                 # An npm package
akm add https://docs.example.com --name docs  # A documentation site

All become searchable immediately. Use akm list to see your sources and akm update --all to keep managed sources current.

Website sources are crawled and converted to markdown knowledge assets. Control the crawl with --max-pages and --max-depth:

akm add https://www.agentic-patterns.com/ --name agent-patterns --max-pages 100

See registry.md for the full install flow and supported ref formats.

Isolated Sandbox Workflow

When testing agent behavior, authoring new assets, or reproducing an issue, you often want a clean stash that does not touch your real one. Every akm command honours the standard XDG env vars plus AKM_STASH_DIR, so you can spin up a disposable environment in a single terminal:

SANDBOX=$(mktemp -d)
export HOME="$SANDBOX"
export XDG_CONFIG_HOME="$SANDBOX/config"
export XDG_DATA_HOME="$SANDBOX/data"
export XDG_CACHE_HOME="$SANDBOX/cache"
export AKM_STASH_DIR="$SANDBOX/stash"

akm setup --yes                 # initialize the sandbox stash
akm index --full                # empty but valid index
akm workflow create demo        # create a template-backed workflow asset
akm workflow start workflow:demo
# ... exercise the flow ...

rm -rf "$SANDBOX"               # tear down when done

Nothing written to $SANDBOX ever reaches your default stash, so this pattern is safe to script into CI or agent test harnesses.

Next Steps

Official akm Repos

If you want the rest of the official akm ecosystem after first-time setup: