Scanning

protomap scan scans the repository that contains a folder and uploads the result to your ProtoMap Server:

bash

protomap scan /path/to/repository

Without a path, it scans the repository you are in. Log in first with protomap login, or set PROTOMAP_URL and PROTOMAP_API_KEY.

The scan runs entirely on your computer: it reads your files with no build and no compiler, then uploads a description of the gRPC code it found, with short code snippets at the locations it records.

What a Scan Reads

A scan reads the repository’s source files in supported languages and its .proto files, apart from what your ignore files leave out:

• .gitignore and .ignore files, as Git does.
• .protomapignore files, in the same format, which take priority over both. Use them to leave out files for ProtoMap only, such as vendored code or examples.

Tests are left out by default, such as tests/ folders and *_test.go files. A .protomapignore at the repository’s root replaces that default, so an empty one scans tests too.

What a Scan Prints

The CLI first shows what it is scanning: the repository, its root folder, the branch, and the commit, with whether it has uncommitted changes and is pushed. It then shows its progress through each stage, and a summary of what it found:

• Service implementations and programs — the code that serves gRPC services, and the code that only calls them.
• Handlers and call sites, with how many call sites could not be linked to a method.
• Dataflows, with how many are uncertain.

The last line says where the scan went: into the shared graph, or private to you, and why.

Add --json to print the result as JSON, such as for a script.

Who Sees a Scan

A scan joins the shared graph, which everyone in your organization sees, when all of these hold:

• The repository has an origin remote other computers can reach, and the remote names a default branch.
• The commit is pushed, and the repository’s primary branch contains it. The primary branch is the remote’s default branch, unless an Admin changed it in the repository’s details.
• There are no uncommitted changes.
• The clone is not shallow, so ProtoMap can tell the commit’s place in history.
• No newer commit of the repository is in the shared graph yet.

Any other scan is a private scan: it shows only to you, laid over the shared graph, in the platform, your chats, and your coding agents. The CLI tells you why, for example:

Uploaded as your private scan, because the worktree has uncommitted changes. Only your queries and chats show it, over the shared graph.

Private scans let you see the effect of a change before you push it. A scan of a commit you just pushed shows to everyone right away, until the next version of the shared graph includes it.

Note

A scan that cannot upload fails, so a CI job notices. A scan the server declines to keep still succeeds, with a notice, such as a scan with an organization API key that cannot join the shared graph: an organization key belongs to no one, so it has no private scans.

Scanner Upgrades

Scans made by a newer release of the CLI may find more. The shared graph switches every repository to the newer release at once: until every repository in it has been scanned with the newer release, the shared graph keeps the older results. Keep your CLIs, and your CI, on the release your server runs.