harumi CLI
Install the harumi CLI, authenticate, and run projects from your terminal.
Overview
The harumi CLI lets you work on a project from your own machine — clone its
repository, run code against Harumi's compute kernels, manage data sources,
and fetch outputs — 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.
Some commands are ahead of the backend
A few commands (marked assumed endpoint in the CLI's own help) are wired
up to an API contract that's still landing on the backend as part of an
ongoing "git-first" migration — schedules and repo provisioning on
projects create, in particular. If a command fails with a "not yet
available" error, that's why: the CLI is ready, but the backend route hasn't
shipped for that exact call yet.
Install
The CLI isn't published to PyPI yet. Install it from the harumi-cli
repository:
pip install -e .Verify the install:
harumi --versionAuthenticate
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 in ~/.harumi/credentials.json (mode 0600). login
also, on a best-effort basis, 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 config set-org <ORG_ID> (see
Commands → Configuration).
Get a project
You need a project (and its git repo) to run against. Either create one from the CLI or bind to an existing one.
Create a project (or find an existing one)
harumi projects create "Demand Planning" # creates + binds this directory
harumi notebooks # list existing projects and reposprojects create binds the current directory automatically (skip with
--no-bind). If you already have a project, grab its ID from
harumi notebooks.
Bind a directory to the project
If you didn't create it via the CLI, bind manually:
harumi init --project <PROJECT_ID>Run once per project directory — writes .harumi/config.json and configures
the harumi git remote for HTTPS + token pushes.
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 --output-dir ./out # block until done, then download
harumi outputs --latest # or check a past runThe 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 --command "python solver.py" --kernel gurobi_python_medium
harumi run --watch --output-dir ./out # block until done, then download outputsProp
Type
VPN required for git operations
git.dev.harumi.io is an internal endpoint — harumi init,
harumi projects create, and any command that pushes code only work while
connected to Harumi's VPN.