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
• 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.

   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.

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

4. Create the cloud project.

   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.

   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 for the full lifecycle.

Git history policy

The default mode is abort-on-findings:

hlix import . --history abort-on-findings

Use preserve only after an explicit review:

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 & syncKeep the local project and the cloud revision head aligned after import.

hlix import referenceEvery flag, the trust gate, and what `--yes` cannot bypass.

Import trust modelWhat import reads, what it executes, and what it makes active.

Quickstart: ship your first taskTake the project you just imported and get agent output from it.