harumi CLI
Install the harumi CLI, authenticate, and run your projects from your terminal.
Overview
The harumi CLI lets you work on a project from your own machine — browse and
edit its repository, run code against Harumi's compute kernels, inspect run
outputs, and manage data sources, secrets, schedules, and organizations —
instead of using the web app. Everything is git-ref based: you point a local
directory at a project once, then run/push like any other git repository.
This page walks you from install to your first run. For the full command reference see Commands, and if something breaks see Troubleshooting.
Install
pipx install harumipipx installs the CLI into its own isolated
environment and puts harumi on your PATH — no virtualenv to manage
yourself. Don't have pipx? Install it first: brew install pipx (macOS) or
python3 -m pip install --user pipx (Linux/Windows).
Verify the install:
harumi --versionPlain pip instead?
pip install harumi works too, but on macOS with Homebrew's Python (or any
PEP 668 "externally managed" install)
it's blocked outside a virtualenv, and pip itself may not even be on
PATH (only pip3). If you hit command not found: pip or an
externally-managed-environment error, either use pipx above, or run
python3 -m pip install --user harumi / pip3 install --user harumi.
Installing from source
Contributing to the CLI, or want an unreleased fix? Clone
harumi-cli and install it
editable instead: pip install -e ..
Using Cursor, Claude Code, or another coding agent?
You don't have to install the CLI yourself — install the
harumi-cli agent skill first and ask your agent to
install the CLI for you.
Authenticate
harumi login # existing account: prompts for email + a one-time code
harumi login --signup # new email: creates the account first, then the OTP
harumi whoami # confirm who you're logged in as
harumi logoutFirst login for a new email?
Pass --signup. Without it, harumi-api rejects the code request with
Signups not allowed for otp. The CLI detects this case and tells you to
retry with harumi login --signup.
Credentials are stored under ~/.harumi/ (mode 0600). login also
provisions a Gitea access token and resolves your organization. If you belong
to more than one organization, it prints them and asks you to pick one with
harumi org use <ORG_ID> (see
Commands → Configuration).
Get a project
Pick a journey
harumi startAsks what you have — nothing yet, a folder of code, or a project that already exists in Harumi — and runs the right command below for you. See Starting a project for the full walkthrough of all three, including their web app equivalents.
Or run the command directly
harumi new "Demand Planning" # nothing yet: create + clone a scaffold
harumi import ./my-project # existing folder: create a project + force-push it in
harumi clone <PROJECT_ID> # existing Harumi project: clone + bindEach of these leaves you with a directory that's bound (.harumi/config.json
written, harumi git remote configured) and ready for harumi run. Already
have the repo checked out by hand and just need to bind it? Use
harumi link --project <PROJECT_ID> instead — it skips the clone/push step.
Run your code
harumi runIf your working tree has uncommitted or unpushed changes, the CLI pushes them to a disposable scratch branch, queues the run against it, and cleans it up afterward — your real branches are never touched. If the tree is already clean and pushed, it runs the current branch directly.
Check the results
harumi run --watch # block until done
harumi runs download -o ./out # download the latest run's output
harumi runs list # recent runs for this project
harumi runs get <RUN_ID> # status, logs (stdout/stderr), and errorsThe run model
harumi run always executes through the project's Harumi Git (Gitea) repo, so
what runs is always a real git ref:
harumi run # current tree (auto scratch push if dirty)
harumi run --branch feature/solver-v2 # a specific branch
harumi run --commit abc123f # a specific commit
harumi run --tag prod # whatever the prod tag points at
harumi run --command "python solver.py" --kernel gurobi_python_medium
harumi run --watch # block until done (then: harumi runs download)Prop
Type
Next steps
Command reference
Every command and flag: projects, files, runs, datasources, secrets, schedules, organizations, and the Python library.
Agent skill
Install the harumi-cli agent skill for Cursor, Claude Code, and other coding agents.
Changelog
What changed in each release, and how harumi tells you about updates.
Troubleshooting
Common errors and how to fix them.