Move an existing project to hlix

hlix import . turns the folder you are standing in into a cloud project, without running any of that project’s own setup commands on your machine. hlix import <folder> does the same for another folder.

When this matters to you

• You have a project on disk and want it under hlix without rebuilding it there.
• You need to know exactly what leaves your machine before you let it.
• A dry run reported a blocker and you want the fix rather than a bypass.

Prerequisites

• The hlix CLI installed
• A completed hlix auth login
• Git installed, even when the source folder is not already a repository
• A project directory you are authorized to upload
• No existing .hlix/config.json binding the folder to a different API or workspace

Review before upload

The importer collects project-local environment and credential files as encrypted protected data, and it scans Git history for likely secrets. Start with a dry run so you know exactly what is in scope before anything moves.

The safe import path

1. Enter the project.

   cd path/to/project

2. Run a dry scan.

   hlix import . --dry-run

   Expected result: a compact report ordered uploaded / skipped / secrets / warnings / blocked. JSON retains the full environment and file report. Secret values are never printed.

3. Resolve every blocker. Do not treat --history preserve as a secret-removal tool. Rotate exposed credentials and remove them from Git history where appropriate. The table further down maps each finding to its fix.

4. Choose the environment file when automatic precedence is wrong.

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

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

   Import also initializes the folder: it creates the cloud project, uploads a verified Git bundle, sends protected files through the encrypted path, and records the first immutable revision. In non-interactive automation, inspect a --dry-run first, then pass --yes to a fresh hlix import invocation — that invocation scans again and binds its own exact result to the upload. --yes never bypasses a blocker.

6. Verify both sides.

   test -f .hlix/config.json
   test -f .hlix/state.json
   hlix projects list

   Expected result: the imported project appears in the table with an initial revision. Refreshing the web app shows the same project in the selected workspace.

7. Make and push a change.

   # edit and test the project first
   hlix push

   Expected result: push complete. A new cloud revision becomes the project head only if the local base still matches the cloud base.

Next: get agent output from it

This page ends with a working project in your workspace, ready for its first piece of work. To go all the way to a task that changed files and the diff behind it, continue with Quickstart: ship your first task.

What you see after import

Import sets the project up; it does not start any work. hlix prepares the project’s Coding Workspace — the code, the environment and its secrets — detects the project’s own dev and test commands, and reads the repository’s documentation (its README, agent instructions and package manifests) to write the project’s description: what it is, what it runs on, and what looks unfinished. Every later request is read against that description, so you do not have to explain the project from scratch.

Open the project in the dashboard to see the team canvas with your agents, the chat, the file tree with the imported files, and the project’s terminal and preview. There are no cycles yet; work starts when you ask for it. Tell the team what to work on in the chat, or send it from the board, Linear, a GitHub issue or the API. Every request goes through triage before it becomes work.

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.

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 copy of the repository. Your source repository is never 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 initialize Git in your source folder.

What hlix detected

The scan looks for explicit development-environment configuration first, then infers the missing pieces from common ecosystem files:

• .cursor/environment.json
• .devcontainer/devcontainer.json or devcontainer.json
• .gitpod.yml
• Docker and Compose files
• package.json and lockfiles
• Python, Go, Procfile, and tool-version files
• environment-variable references and private ports

It can identify toolchain versions, dependency installation, build and start commands, terminal processes, private ports, explicitly required environment keys, and observed source references.

Detection is read-only. init, import --dry-run and import never run the repository’s commands on your machine. An approved setup command runs later in the project’s isolated Coding Workspace, where it can reach project secrets — which is why the import confirmation shows it in full.

See Environment discovery for the detector order, the protected credential sources, and the tooling patterns behind this model.

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 the CLI report. Values and exact protected-file bytes are sent separately. See Secrets & protected files for the full lifecycle.

Git history policy

History is preserved by default. Possible secrets in old commits produce a warning without stopping the import, and the report shows up to five redacted commit-and-file findings. --history preserve and --history abort-on-findings both keep this default behavior.

To leave old commits out, use --history sanitize; local Git history stays intact. Anyone with access to preserved history may recover historical values. Working-tree secret files still travel separately, encrypted, and each is named in the report.

Nested repositories and declared submodules upload their working files without their own Git metadata or history. Ignored nested repositories are skipped silently. Import refreshes a managed block in .hlixignore for verified generated outputs, caches, logs, and untracked agent scratch. Tracked files, source, and secrets are never added automatically, and personal ! overrides are respected. Use --include <path> to include one ignored path, subject to upload limits and secret protection.

Scan warnings and protected-file checks

Never delete .git folders or files to get past a warning; use .hlixignore instead.

Finding	Resolution
Symlinked ignore file	Git does not follow symlinked .gitignore files. Hlix reads a linked .hlixignore target but does not rewrite it; use a regular file for managed-rule refresh. An unreadable target leaves uploads unchanged
File or project too large	Ordinary oversized files are skipped, history is omitted if needed, then the largest folders are skipped until the upload fits. Each skip names a .hlixignore or --include <path> hint
Protected-data limit	Remove unnecessary credential and config copies; keep only the intended environment
Dotenv parse error	Fix the invalid assignments, or select a valid dotenv file with --env-file <path>
Ambiguous dotenv selection	Pass --env-file <path> after reviewing which environment belongs in cloud development

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 approves the reviewed upload and cloud setup. Protected-file checks stay in place, and file limits use the fallback steps above.

Does --history preserve remove the secrets it found? No. It uploads the history with the findings in it, and anyone with access to that history can recover the values. Rotate first, or use --history sanitize to leave old commits out.

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

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

Push, pull & syncKeep the local copy and the cloud revision head in step.

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.