> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basemode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Code

> Commands for the code map: querying entities by name, caller, file and import, listing the maps you have, and the sync that builds and refreshes them.

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.

<Note>
  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.
</Note>

## Querying the code map

Four questions, one command. `base ast query` answers all of them, and which flag you pass decides which question you asked. `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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base ast query --contains "auth"
base ast query --file "main.rs"
base ast query --calls "validate"
base ast query --imports "config.rs"
base ast query --target apps/portal --contains "auth"
```

| Flag                    | Short | What it does                                                                                       |
| ----------------------- | ----- | -------------------------------------------------------------------------------------------------- |
| `--contains <CONTAINS>` | `-c`  | Find entities by name. Case-insensitive substring match, so `auth` finds `authorize` and `reauth`. |
| `--file <FILE>`         | `-f`  | List every entity in one source file, with its relationships.                                      |
| `--calls <CALLS>`       |       | Find every caller of a named entity.                                                               |
| `--imports <IMPORTS>`   | `-i`  | Find every file that imports from the given file.                                                  |
| `--target <TARGET>`     | `-t`  | Query another app's map by path, instead of the map belonging to the directory you are in.         |

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base ast list
```

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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base sync
base sync --incremental
base sync --ast
base sync --ast --target apps/portal
base sync --repair
```

| Flag                | What it does                                                                                 |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `--incremental`     | Only re-extract files that changed since the last sync.                                      |
| `--ast`             | Run the tree-sitter extraction over code instead of the markdown pass. Covers 35+ languages. |
| `--target <TARGET>` | The directory to map. Defaults to the directory you are in.                                  |
| `--repair`          | Backfill missing edges: decision to domain, milestone to project, task to project.           |

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.

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