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

# Run Org Scan yourself

> Run an Org Scan from the command line or a GitHub Actions workflow, and read your Anthropic usage without a key through workload identity federation (WIF).

Org Scan reads the pull-request metadata of the repos you choose, on your own machine or runner. It prints the results in your terminal and emails you a summary. This guide shows how to run it three ways: from a terminal, from a GitHub Actions workflow, and with keyless Anthropic usage reads (WIF).

> [!NOTE]
>
> The `--email` and `--share analytics` options described here need a CLI release that includes the share choices. Check with `mnemom scan --help`: if the `--share` line lists `full`, `analytics` and `none`, you have it. Update with `npm install -g @mnemom/mnemom@latest`.

## What you need

* **Node.js 18 or newer** and the CLI: `npm install -g @mnemom/mnemom`. The package installs a `mnemom` command.
* **A GitHub login that can read the repos.** The scan runs `gh auth token` to get a token, so the [GitHub CLI](https://cli.github.com) (`gh`) must be installed and signed in. The scan only reads pull-request metadata.
* **A Mnemom login as an owner or admin of your org**, with Org Scan switched on for that org. Mnemom refuses members who are not owners or admins. See [Get Org Scan switched on](#get-org-scan-switched-on).

## Get Org Scan switched on

Org Scan is invite-only. It is off for every org until a Mnemom admin switches it on for that org. Org owners and admins cannot switch it on themselves.

To ask for it, an owner or admin of the org emails [support@mnemom.ai](mailto:support@mnemom.ai) with the org id.

Until it is on, a scan still runs on your machine and prints its summary in the terminal. It then prints `Report email is not available for this org yet; nothing was sent.` and no email goes out.

### Find your org id

`--org` takes the org id, like `org-1a2b3c4d`, not the org's name. To find the id, sign in and list your orgs:

```bash theme={null}
mnemom login
mnemom org list
```

The `ID` column holds the org id. The `Role` column shows your role in each org, which must be `owner` or `admin` to run a scan. `mnemom org list` needs a `mnemom login` session. With only `MNEMOM_API_KEY` set, it prints a notice and lists nothing.

## Run it from the command line

Sign in once, then scan:

```bash theme={null}
mnemom login
gh auth login
mnemom scan --org org-1a2b3c4d --repo acme/api --repo acme/web --start 2026-10-01 --end 2026-10-31
```

On a terminal, the CLI asks for anything you leave out: the repos (a picker over the repos your GitHub login can read), the org (when you belong to several), and what Mnemom may keep. When there is no terminal, `--repo` is required and the share choice defaults to `none`.

### Options

| Option | What it does |
| - | - |
| `--repo <owner/name...>` | Repo to scan. Repeat the flag or separate with commas. Omit on a terminal to pick from a list. |
| `--start <YYYY-MM-DD>`, `--end <YYYY-MM-DD>` | The period. Both default to today. |
| `--org <org_id>` | Your org id, like `org-1a2b3c4d`. If omitted, the CLI uses the org from `mnemom org use`, then your only non-personal org. With several orgs and no terminal, it stops and lists them. |
| `--share <level>` | What Mnemom may keep on file: `full`, `analytics` or `none`. See below. |
| `--email <address...>` | Also email the report summary to these people. Repeat the flag or separate with commas. Up to 10, on your organization's email domain or mnemom.ai. |
| `--cto-email <email>` | The older name for one `--email` address. |
| `--monthly-spend <usd>` | Your own approximate monthly AI spend, as a figure like `5000`. Kept in memory only. Needs `MNEMOM_ORG_SCAN_MODE=true`. |
| `--anthropic-admin-key` | Ask for an Anthropic Admin key (masked) and read measured usage with it. Needs `MNEMOM_ORG_SCAN_MODE=true`. See [keyless setup](#read-anthropic-usage-without-a-key-wif). |
| `--no-anthropic-usage` | Skip the Anthropic read and be asked for a monthly figure. Needs `MNEMOM_ORG_SCAN_MODE=true`. |

### Where your report goes

A summary of the report is emailed to you, to every admin of your org, and to anyone you add with `--email`. This happens at every share level. The subject is `Your Mnemom org scan report is ready`, followed by the period. The summary gives totals for the whole scan and never names a repo.

Your terminal shows the pull requests examined, the coverage and, when there is one, the spend line. When the summary was emailed at `--share full`, the terminal also prints the counts for each repo, by name, as JSON under the `Kept on file by Mnemom` line. At `analytics` that JSON has the totals only. At `none` it is not printed. When the summary was not emailed, for any reason, the CLI prints `Kept on file by Mnemom: nothing, because the report was not sent.` and no JSON.

Your terminal output and the emailed summary are the only copies. Mnemom keeps no copy of the report, so there is no report page in the Mnemom dashboard and no link that opens it again. Keep the email, and save the terminal output if you want the counts for each repo. To get a fresh report, run the scan again.

### Choose what Mnemom keeps

The share choice is your permission for what Mnemom may keep. Today Mnemom stores none of the report at any level.

| `--share` | What it allows Mnemom to keep | What Mnemom keeps today |
| - | - | - |
| `full` | The totals and the counts for each repo, by name. In releases up to and including 0.17.44, this is the preselected answer when the CLI asks, so pressing Enter allows it. | A run record and a send log, described below. No report numbers. |
| `analytics` | The team totals only, with no repo names. `summary` is the older name and works the same. | A run record and a send log, described below. No report numbers. |
| `none` | Nothing. In releases after 0.17.44, this is the preselected answer when the CLI asks, so pressing Enter keeps nothing. In every release, it is the answer when there is no terminal and no `--share`. | Nothing. The email is still sent, and Mnemom writes no record of the scan. |

To check which answer your CLI preselects, run `mnemom --version` and `mnemom scan --help`. If the `--share` line calls `none` the default, pressing Enter keeps nothing. If it calls `full` the default, pressing Enter allows the counts for each repo. To keep nothing on any release, pass `--share none` or pick `none` at the prompt.

At `full` and `analytics`, Mnemom may keep:

* **A run record**: the org id, the scan id, the Mnemom account that ran the scan, the time, the share level, and whether the email was delivered. It holds no report numbers, no repo names and no email addresses.
* **A send log**: one entry for each email, with the recipient address and the subject line.

At every level, Mnemom's email provider keeps its own delivery record of each email.

After each scan, the CLI prints a `Kept on file by Mnemom` line naming what the share level allows. To have Mnemom delete anything it holds about a scan, email `privacy@mnemom.ai`.

### If the report is not emailed

| The CLI says | What it means |
| - | - |
| `Report email is not available for this org yet; nothing was sent.` | Org Scan is not switched on for the org. See [Get Org Scan switched on](#get-org-scan-switched-on). You also see this line when you are not signed in to Mnemom and the CLI knows the org from `--org` or `mnemom org use`. Run `mnemom login`, or set `MNEMOM_API_KEY`, and scan again. |
| `Report email is in dry-run on this environment; nothing was sent.` | The Mnemom environment you are pointed at does not send email. |
| `Your report was NOT emailed: not_signed_in.` | Your Mnemom sign-in has expired or was refused. Run `mnemom login` and scan again. |
| `Your report was NOT emailed: not_a_member.` | Your account is not a member of the org, or it is a member but not an owner or admin. Check the `Role` column of `mnemom org list`. |

## Read the report

The email has these parts, top to bottom:

* **The lead.** A dollar figure for AI spend in the period when the report has one. Otherwise the share that passed every check, or, when no share can be shown, the number of merged pull requests examined.
* **A second line under a dollar lead**: the share that passed every check, or the number examined when no share can be shown. A share reads like `About 62% of ... passed every check (an estimate, between 55% and 69% at 95% confidence)`. It is the share of examined merged pull requests whose CI checks all passed. The range is a 95% confidence interval.
* **The period** the scan covers.
* **What the share means**, or why it is not shown. When fewer than 20 pull requests were examined, the email says there is not enough data and shows no share. The email also leaves the share out, and says why, when Mnemom could not confirm a passing accuracy check of the estimate from the last 48 hours.
* **Counted.** How many merged pull requests were examined out of all merged in the period, and whether that is every one or a capped sample. `Not examined` gives the rest.
* **Spend lines.** Each line says where its number came from, described below.
* **Lines that start `Measured,`**: with the modelled range, the number of AI-assisted pull requests for each tool. With measured usage, the share of your tokens in long sessions, where [Mnemom saves the most](https://docs.mnemom.ai/gateway/agent-savings.md).
* **The estimate note** `This is an estimate from PR history, not a measurement.` and the **How we estimated this** link to the method.

### What is measured and what is an estimate

Counts of pull requests, checks and reverts are read from GitHub. The share that passed every check is an estimate from that history. Spend comes from one of three sources, and the CLI picks the first one it has:

| Terminal line | Source | What the email shows |
| - | - | - |
| `Tier 1, measured: ...` | Your Anthropic usage and cost reports, read with WIF or an Admin key. | The measured dollar total is in your terminal only. The email shows `Connect your usage key or tell us your monthly AI spend to see this` in its place, then cost-per-pull-request lines labelled `estimate, from spend for your whole organization`, and the share of your tokens in long sessions. |
| `Tier 2, self-reported: ...` | Your `--monthly-spend` figure. | Nothing from your figure. It is shown in your terminal only and is not sent to Mnemom. |
| `Tier 3, ...` | A modelled range from the AI-assisted pull requests found. | A range labelled `our estimate`, with cost-per-pull-request lines. |

Cost-per-pull-request lines are always labelled `estimate`. With no spend source, the email says `Connect your usage key or tell us your monthly AI spend to see this`. The spend tiers need `MNEMOM_ORG_SCAN_MODE=true`.

### What the scan reads and does not cover

* **GitHub.** Pull-request metadata only, from `api.github.com`: size (lines added and removed, files changed), the CI result, whether it was reverted, the merge date, and marks of AI tools in the pull-request description or commit trailers. Titles and descriptions are checked in memory and dropped. The scan never reads your code.
* **Review state, for a sample of pull requests.** In CLI releases after 0.17.44, the scan also reads the first page of reviews (up to 100) for a sample of the merged pull requests it examined. For each review it keeps only three things: its state (approved, changes requested, or other), whether a person submitted it rather than a bot or app, and when it was submitted. Reviewer logins, user ids, review ids and review text are dropped in memory. From those it keeps two yes-or-no facts for each pull request: whether a person approved it at or before the merge, and whether anyone asked for changes at or before the merge. Reviews submitted after the merge, and dismissed approvals, do not count. A pull request with a full page of 100 reviews is left out. These reads count toward the scan's existing read and time limits, and a failed review read never changes the rest of the scan. The CLI does not show these facts yet and does not send them to Mnemom.
* **AI tools it recognizes.** Claude Code, Codex, GitHub Copilot and Gemini. The modelled range needs at least 10 AI-assisted pull requests.
* **Measured spend covers Anthropic API usage only.** It does not include subscription seats such as Claude Team or Enterprise plans, or spend with any other AI provider.

## Run it in GitHub Actions

`mnemom login` cannot run unattended: it opens a browser or asks you to approve a code. A workflow signs in with a Mnemom API key instead, which the CLI reads from `MNEMOM_API_KEY`.

**1. Create an organization API key**

An owner or admin of the org creates an [organization API key](https://docs.mnemom.ai/guides/api-keys.md) and stores it as the repository secret `MNEMOM_API_KEY`. The owner or admin role is checked on every call, so the key must belong to someone who has it. The report email goes to the person who owns the key, as well as the org admins.

**2. Give the scan a GitHub token**

Store a read-only GitHub token as the secret `ORG_SCAN_GITHUB_TOKEN`. It must be able to read the repos you list. The workflow's built-in `GITHUB_TOKEN` can read only the repository the workflow runs in, so use a fine-grained token with read access to metadata, contents and pull requests for any other repo. The CLI reads the token through `gh auth token`, which returns the `GH_TOKEN` environment variable when it is set.

**3. Add the workflow**

Save the file below as `.github/workflows/org-scan.yml`, and set your org id and repos.

```yaml theme={null}
# .github/workflows/org-scan.yml
name: Org Scan

on:
  workflow_dispatch:
  schedule:
    - cron: "0 15 * * 1" # Mondays

permissions:
  contents: read

jobs:
  org-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install the Mnemom CLI
        run: npm install -g @mnemom/mnemom

      - name: Run the scan
        env:
          GH_TOKEN: ${{ secrets.ORG_SCAN_GITHUB_TOKEN }}
          MNEMOM_API_KEY: ${{ secrets.MNEMOM_API_KEY }}
        run: |
          mnemom scan \
            --org org-1a2b3c4d \
            --repo acme/api --repo acme/web \
            --start "$(date -u -d '30 days ago' +%F)" \
            --end "$(date -u +%F)" \
            --share none
```

Notes on the file:

* There is no terminal in a workflow, so the file passes `--repo` and `--org` explicitly. It also sets `--share` so the choice is yours and not the default. See [Choose what Mnemom keeps](#choose-what-mnemom-keeps). Add `--email cto@acme.com` to send the report to more people.
* The job fails when the report is refused or cannot be sent. If Org Scan is not on for your org, the CLI prints that nothing was sent and the job still passes, so read the log the first time.
* Pin `actions/setup-node` to a commit SHA if your organization requires pinned actions.
* To read Anthropic usage without a key, add the WIF settings from the next section to the same step.

## Read Anthropic usage without a key (WIF)

Org Scan can read your Anthropic usage and cost reports to show measured spend. With workload identity federation (WIF) you do not paste an Admin key. Mnemom issues a short-lived identity token for your org, the CLI exchanges it directly at Anthropic for a short-lived access token, and the CLI uses that token only for the two usage reports. Mnemom never sees the Anthropic token, and nothing in this flow is stored, logged or printed.

Your Anthropic Console holds all the trust settings. Mnemom holds no secret of yours.

### 1. Register Mnemom as a federation issuer

In your Anthropic Console's workload identity federation settings, add an issuer with:

| Setting | Value |
| - | - |
| Issuer URL | `https://api.mnemom.ai/org-scan` |
| JWKS | An explicit URL: `https://api.mnemom.ai/v1/org-scan/wif/jwks.json` |
| Audience | `https://api.anthropic.com` |

### 2. Create a service account and a federation rule

Create a service account, then a federation rule on the issuer that:

* matches the subject `mnemom:org:<org_id>`, with your own org id in place of `<org_id>` (an exact match, or a prefix match with a trailing `*`). Because the subject names your org, an identity token minted for another org cannot satisfy your rule;
* grants the scope **`org:admin`**, which is what Anthropic requires to read the usage and cost reports;
* targets the service account you created.

The identity token also carries the claim `scope = "org-scan"`, if you want the rule to match on it.

> [!NOTE]
>
> A rule written for the command-line scan does not match tokens that Mnemom issues for its own server-side checks. Those use the subject `mnemom:org-server:<org_id>`, so they work only if you add a separate rule for it. Deleting that rule withdraws it at any time.

### 3. Give the CLI the ids

Set these environment variables before the scan. They are ids, not secrets.

| Variable | Value |
| - | - |
| `MNEMOM_ORG_SCAN_MODE` | `true`. Turns on the usage read. |
| `ANTHROPIC_FEDERATION_RULE_ID` | The rule id, starting `fdrl_`. |
| `ANTHROPIC_ORGANIZATION_ID` | Your Anthropic organization id (a UUID). |
| `ANTHROPIC_SERVICE_ACCOUNT_ID` | The service account id, starting `svac_`. |
| `ANTHROPIC_WORKSPACE_ID` | Optional. A workspace id, starting `wrkspc_`. |

With all three required ids set, `mnemom scan` tries WIF first and prints `Read Anthropic usage through workload identity federation.` With none set, WIF is skipped without a message. With only some set, or any malformed, it prints `The Anthropic workload identity settings are incomplete or malformed (federation rule, organization and service account ids).`

In a workflow, add the variables to the scan step. Store the ids as repository variables:

```yaml theme={null}
        env:
          GH_TOKEN: ${{ secrets.ORG_SCAN_GITHUB_TOKEN }}
          MNEMOM_API_KEY: ${{ secrets.MNEMOM_API_KEY }}
          MNEMOM_ORG_SCAN_MODE: "true"
          ANTHROPIC_FEDERATION_RULE_ID: ${{ vars.ANTHROPIC_FEDERATION_RULE_ID }}
          ANTHROPIC_ORGANIZATION_ID: ${{ vars.ANTHROPIC_ORGANIZATION_ID }}
          ANTHROPIC_SERVICE_ACCOUNT_ID: ${{ vars.ANTHROPIC_SERVICE_ACCOUNT_ID }}
```

### If WIF does not work

The CLI prints one fixed sentence and carries on, so the scan still runs.

| The CLI says | What to check |
| - | - |
| `Mnemom did not issue a workload identity token (sign in as an owner or admin of an org with Org Scan on).` | The signed-in user is an owner or admin, and Org Scan is on for the org. |
| `Mnemom could not issue a workload identity token for this org right now.` | Try again later. Mnemom's token service may not be enabled for your environment yet. |
| `Anthropic refused the workload identity token. Check the federation rule in your Anthropic Console (its issuer, subject and scope org:admin).` | The issuer URL, the subject `mnemom:org:<org_id>`, and the `org:admin` scope in the rule. |
| `Anthropic's token exchange could not be completed.` | A network problem or an Anthropic outage. Retry. |

### Fall back to a pasted key

If WIF is not set up or fails, the scan falls back to an Anthropic Admin key. Set `ANTHROPIC_ADMIN_KEY` in the environment, or pass `--anthropic-admin-key` on a terminal to be asked for it (masked; never typed on the command line). When WIF fails and a key is set, the CLI prints `Falling back to the pasted Anthropic Admin key.` The key is kept in memory only and sent only to `api.anthropic.com`. Passing `--anthropic-admin-key` skips WIF and uses the key.

If there is no key either, the scan continues without a measured figure: the next choice is your own monthly figure (`--monthly-spend`), then a modelled range.

## Related

* [API keys](https://docs.mnemom.ai/guides/api-keys.md): create the organization key a workflow uses.
* [Org admin](https://docs.mnemom.ai/guides/org-admin.md): the owner and admin roles that can run a scan.
* [Read the Org Scan value report](https://docs.mnemom.ai/guides/org-scan-value-report.md): the report Mnemom runs for you, how to read its rows, and how to export and verify it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.