Documentation

Using the journeymen CLI

The CLI reads your local git history for a project, shows you exactly what it found, and submits an aggregated report for grading. It never uploads file contents, commit messages, or diffs — see what gets sent below.

Download the CLI

Install

Grab the binary for your platform from the download page. There’s nothing else to install — no Python, no package manager. Rename or move the binary anywhere on your PATH if you’d like to run it as just journeymen instead of the full filename.

journeymen uses GitHub Device Flow — the same identity you’d use signing into the website, verified once. Run:

journeymen auth login

You’ll get a short code and a github.com URL. Open the URL, enter the code, and approve. The CLI stores a journeymen platform token locally at ~/.journeymen/credentials.json — your GitHub token itself is never written to disk.

journeymen analyze <path>

Point the CLI at a local git repository you want scored. It only looks at the exact path you give it — it never scans your disk for other repos on its own.

journeymen analyze /path/to/your/project

This prints a per-author breakdown — commit counts, lines added/removed, and a best-effort language breakdown — along with an explicit statement of exactly what would be sent if you ran submit. Nothing leaves your machine at this step.

journeymen submit <path> --project-id <id>

Runs the same analysis as analyze, then submits the aggregated report for grading, along with your project’s README.md and Graphify-generated graph.json if one exists in the repo.

journeymen submit /path/to/your/project \
  --project-id <your-project-id> \
  [--graph-json /path/to/graph.json]

Find your project ID on its page in the dashboard. Before sending anything, the CLI prints what it’s about to submit and asks you to confirm. Three AI-assisted checks (README-vs-graph consistency, framework detection, AI-dumped-repo detection) run automatically on every submission — see AI checks below.

journeymen identity map <path>

If your local git commits use an email that doesn’t obviously map to one of your verified GitHub handles, the CLI may show it as unresolved. Run this inside the repo to interactively match a local commit email to one of your verified handles:

journeymen identity map /path/to/your/project

The mapping is saved once (~/.journeymen/identity_map.json) and applied automatically in every future analyze/submit, in any repo on that machine. This only affects how your name is displayed — it never changes how a submission is scored; grading always re-verifies identity against GitHub’s own commit data server-side.

AI-assisted checks (compulsory)

Three AI-assisted checks run automatically on every journeymen submit — there is no flag to skip them. They catch things a keyword list can’t: whether your README’s claims actually match your code’s structure, which frameworks/libraries your project uses, and whether an author’s commit timing pattern looks organic relative to the codebase’s size.

journeymen submit /path/to/your/project \
  --project-id <your-project-id>

This CLI never calls OpenAI directly, even with your own key — the call always happens server-side, so the result can’t be forged by a patched CLI. Before each check runs, the CLI prints exactly what it’s about to send so you can see what’s happening as it happens.

By default these use journeymen’s own OpenAI key (rate-capped per day). To use your own key instead:

journeymen ai configure --byok-key <your-openai-key>
# or, to switch back:
journeymen ai configure --platform

A BYOK key is sent with each relay call for that one request only — it is never stored or logged server-side.

What gets sent — and what never is

journeymen only works if you trust it enough to point it at your code — including code under an NDA. Here’s the exact, complete list.

Sent

Per-author commit counts and line add/remove totals
First/last commit timestamps and SHAs (for GitHub-side spot verification)
Each author’s commit email
A per-language line-count breakdown, inferred from file extensions
Your project’s README.md and graph.json, on submit only
On every submit: your README text and a compact structural summary of graph.json (node/community counts and labels only — never full graph.json contents), relayed through journeymen’s server to OpenAI for the three compulsory AI checks — see AI checks

Never sent

File contents
Commit messages
Diffs
A full commit list
Any repo the CLI wasn’t explicitly pointed at

analyze always prints this same disclosure before you’d ever run submit, so you can check it against what’s written here.

Troubleshooting

macOS says the file “cannot be opened because the developer cannot be verified”

Expected — these builds aren’t code-signed yet. Right-click the binary → Open → confirm. You only need to do this once.

Windows SmartScreen blocked the app

Click More info, then Run anyway.

“command not found” after downloading

On Linux/macOS the binary needs execute permission: chmod +x the downloaded file, then run it with ./ in front (e.g. ./journeymen-macos --help), or move it onto your PATH.

I re-ran `submit` after changing my code — did it double count?

No — each submit creates a new analysis run graded independently. Your project’s score reflects your most recent submissions, not a running total.

My name/handle looks wrong in the output