# 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):**

```sh
# 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](https://github.com/itlackey/akm/releases) page.

**Option 2 — Bun (requires [Bun](https://bun.sh) >= 1.0):**

```sh
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:

```powershell
# 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
```

```powershell
# 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:

```sh
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:

```sh
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](technical/filesystem.md) for platform-specific paths and environment
variable overrides.

## Add Your First Asset

Create a simple shell script in the `scripts/` directory:

```sh
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](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:

```sh
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:

```sh
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:

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

See [cli.md](cli.md) for the full set of search flags.

## Show

Inspect an asset by its ref:

```sh
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](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:

```sh
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`:

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

See [registry.md](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:

```bash
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

- [Concepts](concepts.md) -- Asset types, classification, and the stash
- [CLI Reference](cli.md) -- All commands and flags
- [Ref Format](technical/ref.md) -- How asset references work
- [Stash Maker's Guide](stash-makers.md) -- Build and share your own stashes

## Official akm Repos

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

- [itlackey/akm-stash](https://github.com/itlackey/akm-stash) -- install the official onboarding stash with `akm add github:itlackey/akm-stash`
- [itlackey/akm-registry](https://github.com/itlackey/akm-registry) -- browse the official registry source that ships with akm
- [itlackey/akm-plugins](https://github.com/itlackey/akm-plugins) -- optional integrations for editors and agent tools
- [itlackey/akm-bench](https://github.com/itlackey/akm-bench) -- benchmark and evaluation tooling for measuring akm-assisted agent runs
