The CLI in depth

The whole engine, without a window. Good for a terminal you already live in, a machine with no desktop, and anything you want to run unattended.

Two ways to use it

Interactively — akili-code with no arguments opens an agent session in the current folder. This is the one to reach for day to day.

As single commands — ask, edit, verify and the rest do one thing and exit. These are what you put in scripts.

The interactive session

cd ~/projects/my-app
akili-code

Describe an outcome and it plans, works and verifies, streaming as it goes. Ctrl-C cancels the current turn without killing the session.

Commands start with /. Press Tab to complete one — you do not need to remember this table, and /help prints the same list grouped the same way.

Running

/continue also answers to /resume and /go, and a mistyped command suggests the nearest real one rather than only pointing at /help.

On exit, anything still running in the background is named, with stopping one keypress away. It is not stopped automatically — it may be the very thing you are looking at.

Surfaces

Account

The browser flow is the one to use on a machine you trust with a session; the email form is for a server or a container where opening a browser is not an option. /usage reports this session only — your daily allowance lives on the dashboard.

Signing in again as somebody else is how you switch accounts — /login replaces the stored token, and /whoami confirms which one is live. Useful when a personal account and an organisation account share a machine.

Setup

Reading the status line

While a turn is running, the bottom line tells you three things:

⠹ 1m 04s  Running npm install · 48.2s · ctrl-c to stop

• The spinner turns on a clock, not on activity. If it has stopped, the process is wedged — not merely busy.
• The first time is the whole turn. The second is how long the current step alone has taken, and only appears once that step passes five seconds.
• The step name is whatever it is waiting on right now — a file it is reading, a command it is running, or thinking while the model composes its next move.

A total climbing past a minute while each step finishes in under a second is a busy run doing lots of small things. A single step sitting at ninety seconds is the one worth interrupting.

Understanding a codebase

These read and print. Nothing is written, and no model is called except by ask.

akili-code inspect              # languages, layout, build commands
akili-code symbols              # every declared symbol, per file
akili-code graph                # the file dependency graph
akili-code related src/api.rs   # what it needs, and what needs it

inspect is the fastest way to orient yourself in a repository you did not write — and the fastest way to check Akili Code understands it before you trust it with a change.

Asking questions

akili-code ask "where is authentication handled?"
akili-code ask "why does the build fail on Windows?" --model akili-fundi-code

It seeds a context pack from your question, spreads relevance across the dependency graph, and sends only what matters — then cites the paths it relied on. Nothing is written.

Making a change

akili-code edit src/main.rs "add a --version flag"

On its own this proposes a diff and prints it. The flags are what make it useful:

akili-code edit src/parser.rs "handle empty input without panicking" \
  --apply --verify --repair=2 --revert-on-fail

Read that as a contract: change it, prove it, and if you cannot prove it, undo it. The worst outcome is that nothing happened.

Verifying

akili-code verify

Runs the project's detected format, test and build commands and reports pass or fail with the failing output. It exits non-zero on failure, so it works as a CI step or a pre-push hook.

The environment

akili-code env

What the agent can see: shells, toolchains, container runtimes, and on Windows your WSL distributions. Run this first when something the agent needs is "missing".

Running commands

akili-code run "npm test"
akili-code run "Get-ChildItem" --shell powershell

Runs in the project root through a shell you choose, streaming output. Handy for keeping one working directory across a session.

In scripts and CI

Every command exits non-zero on failure, so ordinary shell logic works:

#!/usr/bin/env bash
set -euo pipefail

# Fail the build if the agent cannot make the tests pass.
akili-code edit src/lib.rs "fix the failing rounding test" \
  --apply --verify --repair=2 --revert-on-fail

akili-code verify

Provide credentials through the environment rather than a settings file, which is what a build agent has anyway:

export AKILI_API_BASE="https://api.akilios.dev/v1"
export AKILI_API_KEY="akili_live_…"

Project configuration

akili-code.toml at the project root is committed, so a team shares it:

[defaults]
model = "akili-core"      # cheaper model as the default here
budget = 12000            # context-pack ceiling
max_tokens = 4096

[policy]
denied_tools = ["install_tool"]
denied_patterns = ["docker system prune"]

[verify]
# Override the detected ladder when the project is unusual.
steps = ["cargo fmt --check", "cargo clippy -- -D warnings", "cargo test"]

Keeping it current

akili-code update --check    # look
akili-code update            # install

See Updating.

Getting more out of it

• Describe outcomes, not steps. "Make the CSV importer tolerate missing columns" beats naming files and functions. It reads first; you review the diff.
• Let it verify rather than checking yourself. Adding --verify --repair=2 costs a few more tokens and saves the round trip of finding the failure and telling it.
• Start on Akili Core. Move to Fundi with /model when the reasoning gets hard — you can switch mid-conversation.
• Use --dry-run when a prompt is not landing. Seeing exactly what was sent usually explains why.
• Check .akili-code/audit.log when you want to know what a run actually did, including every refusal and the rule that caused it.