hlix import

Import a local project with its source, history and protected configuration.

hlix import creates a cloud project from a local folder and records its first source commit. Review its plan and approve the upload when prompted.

A hlix.yml in the folder sets the project name, stack, Cloud Machine size, setup, preview, and verification. --name and --stack win and do not change the file. hlix.local.yml overrides that file on this machine. Import uploads the current tree. A hlix.local.yml that was already committed stays in older history under --history preserve; use --history sanitize when that file was committed. A file that cannot be read stops the import and names the field. When the file is missing, import writes hlix.yml after you approve, and a dry run only says that it will.

For what moves and how to resolve each blocker, read Move an existing project to hlix. This page documents arguments and flags.

Prerequisites

A credential that names a workspace (see hlix auth login)
Git installed, even when the source folder is not already a repository
The folder is not already bound to a different API or workspace

Usage

hlix import [folder] \
  [--dry-run] \
  [--env-file <path>] \
  [--history <preserve|sanitize>] \
  [--include <path>] \
  [--name <name>] \
  [--stack <stack>] \
  [--yes] \
  [--json]

Arguments

folder (string, optional, default .): the directory to import, resolved against --cwd. At most one; a second exits invalid_usage.

Flags

--dry-run (boolean, default false): scan and report; upload nothing, create nothing, and write no hlix.yml. With --json, the report is an envelope with files, bytes, protectedFiles and history. A readable plan names the project and whether it will write hlix.yml.
--env-file <path> (string, default: automatic dotenv precedence): choose which dotenv profile is the active cloud environment when the scan finds several. Every other profile is still preserved encrypted. Without it, precedence is .env, .env.development, .env.local, .env.development.local, later overriding earlier.
--history <mode> (preserve | sanitize, default preserve): preserve uploads the Git history; sanitize uploads only the current tree and leaves your local history intact. Any other value exits invalid_usage with --history accepts preserve or sanitize.
--include <path>: include one ignored path inside the project. Upload limits and secret protection still apply. Git metadata is never included.
--name <name> (string, default the folder’s base name): the cloud project name.
--stack <stack> (string, default the detected stack): override stack detection.
--yes (boolean, default false): approve the upload without a prompt, for non-interactive use. It does not bypass scan blockers or secret protection.
--json (boolean, default false): on a real import, returns { files, bytes, protectedFiles, history, projectId, commitSha }. Never contains secret values.

Expected result:

Imported into HLIX Repos: acme-invoices (9f2c1b0)

The approval step

Before creating a project or uploading files, the CLI displays the import plan and asks you to confirm it. The plan includes the project name, source counts, protected paths, MCP definitions, history policy, and warnings:

Import plan
  Project  acme-invoices
  Files    412 files
  Secrets  3 encrypted files
  History  kept

Caller	Behaviour
Interactive terminal, no `--yes`	prompts once; declining exits `0` and uploads nothing
Any caller, `--yes`	proceeds without prompting
`--json` or non-interactive, no `--yes`	exits `invalid_usage`: `Import requires approval. Review --dry-run, then use --yes.`
Any caller, blocker present	exits `scan_blocked` regardless of `--yes`

Each import invocation scans the folder. Resolve blockers shown by that invocation before uploading.

Conflicts and validation

The target is resolved at the folder being imported. An override that contradicts the folder’s binding exits conflict.
A workspace and a credential are both required, or the command exits workspace_required.
A folder already bound to a project exits conflict: This folder is already bound to a project. Use hlix push or sync.
With --history preserve, a history that contains possible secrets, or that could not be scanned completely, exits scan_blocked. Review it, or import with --history sanitize.
The folder is bound before upload, so recover an upload that stopped with hlix push against the same project.

Nested project repositories and declared submodules upload as working files, without their own Git metadata or history.

Import refreshes the Hlix-managed block in .hlixignore before its scan. It keeps your own rules and ! overrides, never adds tracked, source or secret paths to the generated rules, and --dry-run leaves .hlixignore unchanged.

Adjust snapshot scope through .hlixignore.

If import fails

workspace_required — Run hlix auth login to select a workspace.
conflict — This folder is already bound to a project. Use hlix push or sync. Use hlix push.
scan_blocked — the message lists every blocker. Scan warnings and protected-file checks maps each to its fix.
scan_blocked — History contains potential secrets or was not completely scanned. Review it or use --history sanitize.
invalid_usage — Import requires approval. Review --dry-run, then use --yes. Review the dry run, then repeat with --yes.
invalid_usage — --history accepts preserve or sanitize.