hlix init

Reference for hlix init — the files it writes, what it verifies first, and how it differs from import.

hlix init prepares a local folder for the CLI. It writes project configuration and scans the folder. Use hlix import to create the cloud project and upload its files.

Prerequisites

A credential that names a workspace (see hlix auth login)
A directory you are authorized to scan

Usage

hlix init [folder] [--project <id>] [--json]

Arguments

folder (string, optional, default .): the directory to initialize, resolved against --cwd. At most one may be given; a second exits invalid_usage.

Flags

--project (string, optional): bind the folder to a project that already exists in this workspace, instead of leaving it unbound. It refuses a folder already bound to a different project. Afterwards, hlix pull brings the project’s files down — or, when the project has no source files yet, hlix push uploads this folder as its first.
--json (boolean, default false): return { root, config, scan }, where scan carries files, bytes, secretFiles, quarantinedResources, and blocking. Paths and counts only — no secret values.

Expected result:

Initialized /absolute/path/to/project
Project: not imported yet
Workspace: org_2p9xk4

What it writes

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 by `import` or first sync
`.hlixignore`	Project-local additions to the snapshot ignore list	Yes

Conflicts and validation

The target is resolved at the folder being initialized, not the shell’s working directory. An override that contradicts that folder’s existing binding exits workspace_mismatch before anything is written.
If no source in the target chain names a Workspace, the command fails: No workspace selected. Run `hlix auth login --workspace <id>` first.
The CLI verifies the credential before writing the folder binding.
An existing hlix.yml keeps its project setup. Init fills a missing hlix: block and leaves the rest. hlix.api is written only when the server is not https://server.hlix.ai. The folder binding must match the selected Workspace, API and project.
Init appends hlix.local.yml and hlix.local.yaml to .gitignore when those lines are missing. A local file overrides hlix.yml on that machine only. Import uploads the current tree, so a hlix.local.yml that was already committed stays in older history under --history preserve. Use --history sanitize when that file was committed. Init does not create the local file.
Use a regular directory for .hlix.
Scan blockers are reported, not fatal: init prints them under Review before import: and still exits 0. They become blocking at hlix import.

If init 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, 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.
unauthenticated — the stored credential no longer works. Run hlix auth login again.
invalid_usage — more than one folder argument was given.