Initialize a project

Bind a local folder to the authenticated hlix workspace and create safe, reviewable project configuration.

hlix init prepares local project configuration and binds the folder to a Workspace. Use hlix import to create a cloud project and upload its files.

Prerequisites

The CLI is installed
You are authenticated
The target is a directory you are authorized to scan and upload

Initialize the current folder

cd path/to/project
hlix init

Initialize a different folder without changing directories:

hlix init path/to/project

Bind a folder to a project that already exists in your workspace, then pull its files:

hlix init --project <project-id>
hlix pull

--project refuses a folder that is already bound to a different project. The desktop app’s Local folder tab runs exactly these two commands when you choose a folder.

If the project has no cloud files yet — for example, a new dashboard project — push instead. Your folder becomes its first source commit:

hlix init --project <project-id>
hlix push

Expected result when initializing a folder without --project:

Hlix ignored 6 generated folders — see .hlixignore
Initialized /absolute/path/to/project
Project: not imported yet
Workspace: <workspace-id>

The command verifies the current login, scans the folder, and creates:

Path	Purpose	Commit it?
`hlix.yml`	The project file. `hlix.workspace` and `hlix.project` bind the folder. `hlix.api` is written only when the server is not `https://server.hlix.ai`; a missing key means that host. The rest is Cloud Machine size, setup, preview, verification, and environment variable names. Secret values stay out of it. An existing file keeps its project setup. Init fills a missing `hlix:` block and leaves the rest.	Yes
`.hlix/.gitignore`	Keeps local synchronization state out of Git	Yes
`.hlix/state.json`	Last synchronized repository, commit, and file identities	No; created after import or first sync
`.hlixignore`	Project-local additions to the snapshot ignore list	Yes

Init also appends hlix.local.yml and hlix.local.yaml to .gitignore when those lines are missing. That file overrides hlix.yml on this machine. Import uploads the current tree, so a copy already committed stays in older history under --history preserve. Use --history sanitize when that file was committed. Init does not create it.

Review the scan

Human output calls out blocking findings. For a complete machine-readable report:

hlix init --json

The JSON envelope includes file and byte counts, protected paths, quarantined resources, and blockers. It does not include secret values.

Customize snapshot scope

hlix init, hlix import and hlix push maintain a marked block in .hlixignore for detected build output, caches and temporary files. Keep your own rules outside it:

# Your own rules
.playwright-cache/
tmp-fixtures/
!dist/keep.log
# --- managed by Hlix: safe to edit above/below, this block is regenerated ---
/.next/
/coverage/
# --- end managed by Hlix ---

Your rules and ! overrides are preserved. Track authored files in Git or add a ! override when they live inside a generated output directory. Use --include <path> on import or push to retain another ignored path in future scans.

Review and commit .hlixignore with the project. Dotenv and recognized credential files use the separate protected-file path.

Verify initialization

ls hlix.yml .hlix/.gitignore .hlixignore
git status --short

Expected result: those three files exist, while .hlix/state.json is still absent until a successful import or first sync. The workspace and project id are in the hlix: block of hlix.yml. hlix.api is in that block only when the server is not https://server.hlix.ai.

If initialization fails

No workspace selected. Run `hlix auth login --workspace <id>` first. — nothing in the resolution chain named a workspace.
workspace_mismatch: a --workspace, --base-url, or HLIX_* value contradicts the binding of the folder being initialized. The message names both sides. Drop the override rather than editing the hlix: block to match, and use a folder bound to the intended project.
Refusing to write through a symlinked …: replace the symlinked .hlix path with a real directory you own.
Scan blockers: follow the recovery steps in Move an existing project to hlix.