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 — 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 ..
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 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 projects list # list existing projectsprojects create binds the current directory automatically (skip with
--no-bind). If you already have a project, grab its ID from
harumi projects list.
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 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 --command "python solver.py" --kernel gurobi_python_medium
harumi run --watch --output-dir ./out # block until done, then download outputsProp
Type