litmus-cli

Official CLI for Litmus engineering assessments.

Installation

npm install -g litmus-cli

Requires Node.js 18+.

Usage

Initialize an assessment

litmus init <token>

• Downloads the assessment package
• Installs dependencies automatically
• Initializes a git repo with an initial commit
• Starts background file tracking
• Your timer begins when you run this command
• Your work is automatically submitted when the time limit is reached — if auto-submit fails, run litmus submit manually within 5 minutes of the deadline

Your token is provided on the Litmus candidate portal when you open your assessment.

Check your status

litmus status

Run this from inside your assessment folder to see:

• Time elapsed and remaining
• Deadline info
• Git commit stats
• Estimated submission size
• Tracker status

Submit your work

litmus submit

Run this from inside your assessment folder when you're done. It packages your work (source code + git history + activity log) and uploads it automatically. The assessment folder is deleted after a successful submission.

Use litmus submit --yes to skip the confirmation prompt.

How it works

1. litmus init <token> — sets up your workspace and starts the clock
2. Work in your preferred editor, committing frequently
3. litmus status — check your progress and time remaining
4. litmus submit — packages and uploads everything in one step

Your git commit history and file activity are included in the submission and used as part of the evaluation. Frequent, meaningful commits are recommended.

What gets sent to Litmus during your session

While you're working, the background tracker sends activity data to Litmus in addition to the submission ZIP you upload at the end:

• File-change events, git commits, and AI-tool usage detected on your machine (process list, network endpoints) — every few seconds while you work.
• Captured AI prompts from Claude Code, Codex CLI, and Copilot CLI when those tools fire UserPromptSubmit hooks. Copilot Chat (VS Code side panel) is not hookable and is not captured.
• A periodic codebase snapshot (every five minutes) so the optional live-interview agent has up-to-date context. Snapshots are capped at 2 MB total and skip binaries, dotfiles (including .env), lockfiles, node_modules/build directories, and obvious credential filenames (secrets.*, credentials.*, *.pem, *.key, id_rsa, etc.). If you have sensitive material in a non-standard filename, move it out of the assessment directory before working.

You can confirm what's installed and what's being captured at any point with litmus status.

Requirements

• Node.js 18+
• Git (recommended — without it, analysis loses commit history, iteration patterns, and process scoring signals; code quality scoring still works)

Releasing (maintainers)

Releases are automated by the CLI Publish GitHub Actions workflow. Do not run npm publish by hand — the workflow publishes via npm OIDC trusted publishing (no npm login or token needed), and a manual publish skips the build/test gate and the GitHub release.

To cut a release:

1. Bump the version in cli/package.json and merge it to main through a PR (main is protected, so direct pushes are rejected).

2. Push a tag matching cli/vX.Y.Z, where X.Y.Z exactly equals the version you just merged into cli/package.json:

   git tag cli/v1.3.2
   git push origin cli/v1.3.2

The tag push triggers the workflow, which builds and tests the CLI on Linux + Windows (e2e excluded — they need a seeded DB), verifies the tag matches package.json, publishes to npm, and creates a GitHub release with generated notes.

Notes:

• The trigger is the tag pattern cli/v* and nothing else. A tag like v1.3.2 or litmus-cli-v1.3.2 will not fire the workflow.
• The tag version must match package.json or the publish job fails its verify step.
• npm rejects re-publishing an existing version — never re-tag a version that is already on the registry; bump to a new version instead.