Skip to content
hlix docs

hlix init

hlix init prepares a local folder for the CLI. It writes committable project configuration and scans the folder, but it creates no cloud project — hlix import does that and adds the project and revision IDs.

Prerequisites

Section titled “Prerequisites”
  • A credential that names a workspace (see hlix auth login)
  • A directory you are authorized to scan

Usage

Section titled “Usage”
Terminal window
hlix init [folder] [--json]

Arguments

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

Flags

Section titled “Flags”
  • --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

Section titled “What it writes”
Path Purpose Commit it?
.hlix/config.json Stable API URL, workspace ID, and — after import — project ID Yes
.hlix/.gitignore Keeps local revision state out of Git Yes
.hlix/state.json Last synchronized immutable revision and generation No; created by import
.hlixignore Project-local additions to the snapshot ignore list Yes

Conflicts and validation

Section titled “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.
  • Nothing in the chain naming a workspace is an error, not a default: No workspace selected. Run `hlix auth login --workspace <id>` first.
  • The credential is proved with a real projects.list call before the folder is bound. init must not leave a convincing config behind for a dead login.
  • An existing .hlix/config.json is preserved rather than rewritten, so a routine init cannot silently move work across tenants.
  • A symlinked .hlix path is refused.
  • 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

Section titled “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 .hlix/config.json, and never copy that file between projects or tenants.
  • Refusing to write through a symlinked … — replace the symlinked .hlix path with a real directory you own.
  • unauthenticated — the stored credential no longer works. init proves it before writing, so this means the login is stale, not that the folder is wrong.
  • invalid_usage — more than one folder argument was given.

Next steps

Section titled “Next steps”
hlix importCreate the cloud project and its first immutable revision.
Initialize a projectThe walkthrough, including .hlixignore scope and what to commit.
Environment discoveryWhat the scan looks for, in what order, and what it refuses to collect.
CLI referenceGlobal options, the JSON envelope, and every error code.