Initialize a project

hlix init prepares a folder for the CLI. It does not create a cloud project; hlix import does that and adds the project and revision IDs.

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

Expected result:

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/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 after import
.hlixignore	Project-local additions to the snapshot ignore list	Yes

One folder, one binding

If the folder is already initialized for another workspace or API, hlix init refuses to rewrite it. This prevents a routine command from silently moving work across tenants.

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

Add generated or local-only paths to .hlixignore using Git-ignore syntax:

.playwright-cache/
tmp-fixtures/
large-local-dataset/

The default scanner already excludes .git, .hlix, dependency folders, common build outputs, caches, coverage, virtual environments, and operating-system metadata.

Do not use .hlixignore to hide a credential that should be moved safely. Dotenv and recognized credential files belong in the protected-file path described in Secrets & protected files.

Verify initialization

test -f .hlix/config.json
test -f .hlix/.gitignore
test -f .hlixignore
git status --short

Expected result: the three configuration files exist, while .hlix/state.json is still absent until a successful import.

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 .hlix/config.json to match — 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.
• Scan blockers: follow the recovery steps in Import a project.

Next steps

Import a projectCreate the cloud project and its first immutable revision.

hlix init referenceEvery flag, what it validates first, and what it refuses to overwrite.

Environment discoveryWhat the scan looks for, in what order, and what it never collects.

Secrets & protected filesWhere a credential belongs instead of `.hlixignore`.