Starting a project
Three ways to get code into Harumi — pick the one that matches what you have.
Which journey are you on?
Every Harumi project is a git repository plus a harumi.toml that says what to run.
How you get there depends on what you're starting from:
1. Nothing yet
Start from an empty project with a working scaffold.
2. A folder of code on your machine
Turn an existing local project into a Harumi project.
3. A project that already exists in Harumi
Get its code onto your machine.
Using the CLI? harumi start asks this same question interactively and runs
the right command for you — everything below is what it does under the hood.
1. Nothing yet
You have no code and no project. Harumi creates the project, provisions its
git repository, and seeds it with a runnable scaffold (harumi.toml,
main.py, dashboard/overview.toml) — so there's something to run immediately.
Create the project
From your projects home, click New project and pick the workspace (personal or an organization) it belongs to. Not sure where to start? Click Describe my problem instead: tell Harumi what you want to improve in your own words and the assistant sets the project up and builds its checklist.
Run it
Open the Code tab to see the scaffold, then click Run in the toolbar. See the Quickstart for what each scaffold file does.
2. A folder of code on your machine
You already have code — a script you've been iterating on, an old GitHub
repo, a colleague's zip. Harumi creates a new project, then makes your
folder's contents the repo's first commit. This overwrites the
server-seeded scaffold with your files, so if your folder has no
harumi.toml one gets written for you before pushing (with python main.py
as a starting guess — edit it if your entry point differs).
Start a new project from your files
From your projects home, click
New project. In the dialog, open Advanced options, then drop a
.zip of your folder under Start from a ZIP or folder (optional),
or select it directly (folder upload is also supported).
Create the project
Click Create project. The project starts with exactly your files
instead of the default ones — a harumi.toml needs to be part of what
you upload, or harumi run will fail with a missing manifest
afterward.
Why this force-pushes
The freshly-provisioned repo only has a scaffold commit — there's no shared history with your local folder for a normal push to merge against. Force-push is the only way in; it's safe because the repo was just created for this.
3. A project that already exists in Harumi
Someone already created the project — via the web app, the CLI, or a teammate — and you just need its code on this machine.
Open the project's Code tab and copy the Clone URL at the top, then:
git clone <CLONE_URL>This gets you the code, but not a Harumi-aware directory — you'll still
need harumi link --project <PROJECT_ID> (see the CLI tab) to bind it so
harumi run works.
Directory already checked out?
If you already have the repo cloned by hand (e.g. via the web app's Clone
URL, or you moved a directory that was bound before), harumi clone would
try to clone into an existing, non-empty folder and fail. Use
harumi link --project <PROJECT_ID> instead — it only writes
.harumi/config.json and configures the git remote, without touching your
checkout.