# 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`](/reference/cli/import/) does that and adds the project and revision IDs.

## Prerequisites

- A credential that names a workspace (see [`hlix auth login`](/reference/cli/auth/))
- A directory you are authorized to scan

## Usage

```bash
hlix init [folder] [--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

- **`--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:

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

## 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

- 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`](/reference/cli/import/).

## If init fails

- ``No workspace selected. Run `hlix auth login --workspace <id>` first.`` — nothing in the [resolution chain](/reference/cli/#where-a-command-points) 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

[hlix import](/reference/cli/import/)
  [Initialize a project](/cli/init/)
  [Environment discovery](/cli/environment-discovery/)
  [CLI reference](/reference/cli/)