# Import a project

`hlix import .` creates a cloud project from the folder you are standing in. `hlix import <folder>` does the same for another folder.

## Prerequisites

- The CLI is [authenticated](/getting-started/authentication/)
- Git is installed, even when the source folder is not already a repository
- You have reviewed what the selected folder may contain
- No existing `.hlix/config.json` binds the folder to a different API or workspace

## The safe import path

1. **Run a dry scan.**

   ```bash
   hlix import . --dry-run
   ```

   Expected result: a key-only report of the stack, ordinary files, environment sources, secret-key count, protected resources, historical findings, and blockers.

2. **Resolve every blocker.** Do not treat `--history preserve` as a secret-removal tool. Rotate exposed credentials and remove them from Git history when appropriate.

3. **Choose the environment file when automatic precedence is wrong.**

   ```bash
   hlix import . --dry-run --env-file .env.development
   ```

4. **Create the cloud project.**

   ```bash
   hlix import . --name "Payments service"
   ```

   `--name` defaults to the folder name. `--stack` can override stack detection.
   When setup commands, protected files, or quarantined resources were found,
   the CLI shows their commands, paths, and secret **key names** and asks for
   one explicit trust decision. Automation should inspect a `--dry-run`, then
   pass `--yes` to a fresh import invocation. That invocation scans again and
   binds its own exact result to the upload; `--yes` never bypasses a blocker.

5. **Verify both sides.**

   ```bash
   hlix projects list
   test -f .hlix/state.json
   ```

   Refresh the hlix web app in the same workspace. The project should appear with an initial revision.

## What gets moved

One folder splits into three lanes: snapshot files go into the uploaded Git bundle, protected files take a separate encrypted path outside Git, and quarantined resources are preserved encrypted but never activated.

The importer separates the folder into three lanes:

| Lane | Examples | Result |
| --- | --- | --- |
| Snapshot files | source, tests, lockfiles, docs, untracked work not ignored | copied into a temporary repository and uploaded in a verified Git bundle |
| Protected files | dotenv, credentials, keys, `.npmrc`, `terraform.tfvars`, high-confidence secret content | excluded from Git and uploaded through encrypted protected storage |
| Quarantined resources | `AGENTS.md`, `CLAUDE.md`, skills, `.mcp.json` | encrypted and preserved, but not activated during project import |

Dirty and untracked snapshot files are included in an explicit import-snapshot commit created in a temporary clone. The source repository is not committed, rebased, or rewritten.

Git history reachable from the local branches and tags captured by the approved scan is preserved in the bundle. A ref created or changed after approval is excluded or stops the snapshot. For a non-Git folder, hlix creates the history inside the temporary snapshot; it does not run `git init` in your source folder.

## Environment discovery

The scan looks for explicit development-environment configuration first, then infers missing pieces from common ecosystem files. It can identify toolchain versions, dependency installation, build and start commands, terminal processes, private ports, explicitly required environment keys, and observed source references.

Repository commands remain untrusted strings during the local scan. They are not executed locally by `init`, `import --dry-run`, or `import`. Approved setup runs later inside the isolated Coding Workspace before a cloud task, where it can access project secrets; this is why the import confirmation lists it verbatim.

## Secret handling

Dotenv precedence for automatic development selection is:

1. `.env`
2. `.env.development`
3. `.env.local`
4. `.env.development.local`

Later files override earlier values. If that is not the intended cloud-development environment, pass `--env-file <path>`.

Only key names, hashes, sizes, and paths appear in the manifest and CLI report. Values and exact protected-file bytes are sent separately. See [Secrets & protected files](/security/secrets/) for the full lifecycle.

## Git history policy

The default mode is `abort-on-findings`:

```bash
hlix import . --history abort-on-findings
```

Use `preserve` only after an explicit review:

```bash
hlix import . --history preserve
```

`preserve` means “upload the history despite findings.” Anyone with appropriate access to that repository history may still recover historical values. Rotate exposed credentials before importing.

## If the scan blocks the import

| Finding | Resolution |
| --- | --- |
| Potential secret in history | Rotate it, rewrite/sanitize history where appropriate, then scan again |
| History scan incomplete | Review the repository separately, then explicitly choose `--history preserve` if retaining it is intended |
| Nested repository | Import the nested repository separately |
| Symlink | Replace it with an in-root regular file/directory or exclude it; symlinks are refused in this release |
| File or project too large | Exclude generated/local-only data with `.hlixignore` or split the project intentionally |
| Protected-data limit | Remove unnecessary credential/config copies and keep only the intended environment |
| Dotenv parse error | Fix invalid assignments or select a valid dotenv file |

## Common questions

**Does import need a GitHub connection?** No. Import creates the project directly in your workspace from local files and history. Connecting a repository is a separate, later choice.

**Are my secrets in the Git bundle?** No. Protected files travel a separate encrypted path and are excluded from the bundle entirely. The manifest and every report carry key *names*, hashes, sizes and paths — never values.

**Can `--yes` get me past a blocker?** No. `--yes` records approval for the reviewed upload and cloud setup. Blockers — history findings, unsafe paths, integrity failures, size limits — are refused regardless of it.

**Does `--history preserve` remove the secrets it found?** No, and this is the most important misreading on this page. It means "upload the history *despite* the findings". Anyone with access to that history can still recover the values. Rotate first.

**I imported the wrong folder. What now?** Nothing was rewritten locally — import never commits, rebases, or alters your source repository. Delete the cloud project and re-import; the local `.hlix/config.json` is the only thing to clean up.

## Integrity and concurrency

The CLI hashes the manifest and bundle, verifies the bundle before upload, and rechecks files while building the snapshot. If the source changes between scan and snapshot, import stops instead of uploading a mixed state.

Import finalization records an immutable revision. Repeating the same request uses an idempotency key so an interrupted retry does not create duplicate projects.

## Next steps

[Push, pull & sync](/cli/sync/)
  [hlix import reference](/reference/cli/import/)
  [Import trust model](/security/trust-model/)
  [Quickstart: ship your first task](/getting-started/quickstart/)