# 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](/getting-started/quickstart/).

## Prerequisites

- The [`hlix` CLI installed](/getting-started/install/)
- A completed [`hlix auth login`](/getting-started/authentication/)
- 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.**

   ```bash
   cd path/to/project
   ```

2. **Inspect the import plan.**

   ```bash
   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.**

   ```bash
   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.**

   ```bash
   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.**

   ```bash
   # 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](/cli/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 task](/getting-started/quickstart/)
  [Push, pull & sync](/cli/sync/)
  [Secrets & protected files](/security/secrets/)
  [Import skills, agents & MCP servers](/cli/resources/)