Quickstart

1. Install mikro

   1curl -fsSL https://raw.githubusercontent.com/automagik-dev/mikro/main/scripts/install.sh | bash

   The installer clones mikro into ~/.mikro/mikro, builds it, and links the mikro command into ~/.local/bin, which must be on your PATH. mikro is installed from git and is not published to npm.

   Verify the install:

   1mikro --version

   It prints the installed version, for example mikro v1.260909.1. Later, mikro update fetches the newest main commit and rebuilds in place.

   mikro requires Node.js 22.19.0 or later, Python 3.10+ (for the REPL subprocess) and git. Make sure all three are available on your PATH.
2. Set your API key

   mikro uses Google Gemini by default. Set your API key:

   1mikro config set GEMINI_API_KEY your-api-key-here

   Google Gemini (default)AnthropicOpenAI

   1mikro config set GEMINI_API_KEY your-key

   Settings are stored at ~/.mikro/settings.json with 0600 permissions. A model.provider, model.model or model.sub-call-model set here takes precedence over the model: block in a project's .mikro/mikro.yaml. Set model.sub-call-model whenever you change the provider, because the mikro.yaml that mikro scaffolds names a Gemini model for llm_query() sub-calls, and that model fails on any other provider.
3. Initialize a project

   Navigate to your project directory and scaffold a config:

   1mikro init

   This creates a .mikro/ directory holding mikro.yaml, with sensible defaults and inline comments explaining every option, plus SYSTEM.md, CRITERIA.md and TOOLS.md. You can skip this step: mikro scaffolds .mikro/ on the first query if no config exists.
4. Run your first query

   Point mikro at some context and ask a question:

   1mikro "How does authentication work?" --context ./src/ --ext .ts,.js

   mikro loads your source files into a Python REPL, then iterates: it writes Python code to navigate the context, executes it, and refines until it calls FINAL() with the answer. A --context directory loads only .md files unless you pass --ext or set context.extensions in mikro.yaml.

   Text output (default)JSON outputVerbose output

   123456$ mikro "How does authentication work?" --context ./src/ --ext .ts,.js
   
   Authentication uses JWT tokens issued by the /auth/login endpoint.
   The middleware in src/middleware/auth.ts validates tokens on every
   request and attaches the decoded user to req.user. Refresh tokens
   are stored in HttpOnly cookies with a 7-day expiry.
5. Try different input modes

   mikro reads directories and single files as context, and it can read the query itself from a pipe:

   1234567891011121314# Directory of docs (recursively loads .md files by default)
   mikro "Summarize the API" --context ./docs/
   
   # Single file
   mikro "What are the key findings?" --context paper.md
   
   # Any single file other than JSON is read as one string
   mikro "Analyze this dataset" --context data.csv
   
   # Piped query: stdin is read as the query when no query argument is given
   echo "Summarize the API" | mikro --context ./docs/
   
   # Custom file extensions
   mikro "Review this code" --context ./src/ --ext .ts,.js,.py

   When a query argument is present, mikro does not read stdin, so pass data files with --context.

Output modes

What just happened?

1. Loaded your files into a persistent Python subprocess as the context variable
2. Sent the LLM a system prompt with metadata about the context (not the content itself)
3. The LLM wrote Python code to search, filter, and read specific parts of the context
4. mikro executed each code block and fed the results back
5. After a few iterations, the LLM called FINAL() with its answer

Next steps