Skip to main content
base keeps a separate map of your code, built by tree-sitter, and every one of these commands reads from or rebuilds that map. Two commands cover it: base ast asks the map questions, and base sync --ast builds it. The map lives with the app it describes, at <app>/.base-ast/ast.ttl, so a workspace with several apps has several maps rather than one shared index.
Every command on this page is read-only except base sync, which writes to the graph and to the code map. Nothing here removes anything.

​
Querying the code map

One command, and the flag you pass decides which question you asked. Four flags cover the common questions and --relation reaches every other relation the map holds. base ast list tells you which maps exist to ask. Aliases: base a for base ast, q for query, l for list. base a q -c "auth" and base ast query --contains "auth" are the same command.

​
base ast query

Find entities by name, list what is in one file, find every caller of a function, or find every file that imports from a file.
--target is the flag worth remembering. Without it, base ast query reads the map for your current directory, which means answering a question about apps/portal from the workspace root returns nothing rather than an error. With --target apps/portal you can ask from anywhere.

​
base ast ensure

Make sure the app containing PATH has a code map: build one in the background if it has none, do nothing if it has (what the hooks do on first contact; the Windows hooks call this inside WSL for Linux paths).

​
base ast list

Show every code map registered in this workspace, with its app name, how many entities it holds, its path, and when it was last synced.
Run this first when a query comes back empty. An app with no row here has never been mapped, and no amount of querying will find it. It needs base sync --ast --target <path> once.

​
base sync

Read file-owned data into the graph. Run with no flags, it extracts your markdown: frontmatter and body, from the files base already knows about. Run with --ast, it builds the code map instead.
Map a new app once with base sync --ast --target apps/portal. After that it stays current on its own, and you only need to run it again if you want to force a rebuild.

​
Exit codes

Exit 3 is new in 0.16.0. Before it, one file whose frontmatter held a value the graph cannot store stopped the whole sync before anything was written. Now that file is named on stderr (the file, the field and the value), every other file is written, and the last line says how many were not synced. The graph keeps what it held for the skipped files before. A script that treats any non-zero code as failure should read 3 as “written, with the files named”. A symlink or Windows junction that leads into a folder sync.exclude keeps out is skipped too, with one line naming the link and where it leads.

​
The 15-minute limit on automatic builds

The code-map builds base starts by itself, from the hooks, run as base sync --ast --yes. Since 0.16.0 they stop after 15 minutes, along with everything they started, so a build that hangs cannot run forever. The next session start says so, and keeps the old map if there was one:
A base sync --ast you run by hand without --yes has no time limit. --repair is for one specific symptom: a project whose tasks or milestones exist but do not show up attached to it, or a decision that a domain-scoped search cannot find. It rebuilds those links and changes nothing else.