Move an existing project to hlix

This path moves the project in your current directory into the authenticated hlix workspace without executing repository setup commands on your machine.

Looking for the Quickstart?

This page covers the import half. To go all the way to agent output — a running orchestrator, a task that changed files, and the diff behind it — start with Quickstart: ship your first task.

Prerequisites

• The hlix CLI installed
• A completed hlix auth login
• Git installed
• A project directory you are authorized to upload

Review before upload

The importer collects project-local environment and credential files as encrypted protected data. It also scans Git history for likely secrets. Start with a dry run so you understand exactly what is in scope.

1. Enter the project.

   cd path/to/project

2. Inspect the import plan.

   hlix import . --dry-run

   Review the stack, file and byte counts, active environment files, secret-key count, environment confidence, quarantined resources, history findings, and any blockers. Secret values are never printed.

3. Import the project.

   hlix import .

   Review the trust summary and confirm. 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, review a dry run first and then use hlix import . --yes.

4. Verify the local binding.

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

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

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

What hlix detected

The scan builds a declarative environment plan from repository evidence such as:

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

Detection is read-only. Install, build, start, and terminal commands are recorded for review; they are not executed by the local scan. Approved cloud setup may run later inside the isolated Coding Workspace.

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

If the dry run blocks

Do not bypass a blocker until you understand it.

• Potential secrets in Git history: remove and rotate them. --history preserve is an explicit choice to keep that history; it does not make exposed credentials safe.
• Incomplete history scan: repositories above the scan limit require an explicit --history preserve decision.
• Symlink: this release refuses symlinks rather than following a path outside the selected root.
• Nested Git repository: import each repository independently.
• Ambiguous dotenv selection: pass --env-file <path> after reviewing which environment belongs in cloud development.
• Size limit: exclude generated or unnecessary data with .hlixignore.

Next steps

Quickstart: ship your first taskNow start a run and read what an agent delivered.

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

Secrets & protected filesExactly how credentials move to cloud, and what never does.

Import skills, agents & MCP serversActivate the trusted resources import only quarantines.