# Initialize a project

`hlix init` prepares a folder for the CLI. It does not create a cloud project; [`hlix import`](/cli/import/) does that and adds the project and revision IDs.

## Prerequisites

- The CLI is [installed](/getting-started/install/)
- You are [authenticated](/getting-started/authentication/)
- The target is a directory you are authorized to scan and upload

## Initialize the current folder

```bash
cd path/to/project
hlix init
```

Initialize a different folder without changing directories:

```bash
hlix init path/to/project
```

Expected result:

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

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

```text
.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](/security/secrets/).

## Verify initialization

```bash
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](/reference/cli/) 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](/cli/import/#if-the-scan-blocks-the-import).

## Next steps

[Import a project](/cli/import/)
  [hlix init reference](/reference/cli/init/)
  [Environment discovery](/cli/environment-discovery/)
  [Secrets & protected files](/security/secrets/)