Skip to content
hlix docs

hlix projects

hlix projects reads the projects in the resolved workspace. Both commands are transport-only: with --json the body is the API’s response passed through unmodified, so a script never finds that the CLI dropped a field the API returned.

Prerequisites

Section titled “Prerequisites”

hlix projects list

Section titled “hlix projects list”
Terminal window
hlix projects list [--json]

Lists every project in the workspace the target chain resolved. It takes no positional arguments and no command-specific flags.

Expected result:

ID                                    NAME            STACK
------------------------------------  --------------  ------
6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41  acme-invoices   bun

An empty workspace prints No projects. and exits 0.

hlix projects get

Section titled “hlix projects get”
Terminal window
hlix projects get [project-id] [--json]

Arguments

Section titled “Arguments”
  • project-id (string, optional, default the bound project): which project to show. With no ID, the project this folder is bound to is used — found by walking up from --cwd. Outside a bound folder, omitting it exits missing_argument: A project id is required, or run this inside a folder bound to a project.

Expected result:

id      6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41
name    acme-invoices
stack   bun
status  active
repos   1

Conflicts and validation

Section titled “Conflicts and validation”
  • The human view selects columns and omits empty fields; the --json body does not. Read the envelope, not the table.
  • A project in another workspace answers not_found rather than forbidden — the API does not confirm cross-tenant existence, and neither does the CLI.
  • At most one positional argument; a second exits invalid_usage.

If a projects command fails

Section titled “If a projects command fails”
  • unauthenticated — No credential. Run `hlix auth login`, or set HLIX_API_KEY for CI.
  • forbidden — the key is valid but the user cannot act in the resolved workspace.
  • not_found on projects get — the ID is wrong, or belongs to a workspace this key cannot see. Do not infer which.
  • workspace_mismatch — an override contradicts the folder’s binding. hlix status shows which source decided what.
  • missing_argument — run it inside a bound folder, or pass the ID.
  • unreachable — the API could not be contacted; the failure is transport, not authorization.

Next steps

Section titled “Next steps”
hlix tasksList, inspect, watch, and read the review evidence for a project's tasks.
TasksHow tasks are created, why execution comes from a cycle, and every status.
hlix statusWhich workspace and project this folder actually resolves to.
CLI referenceThe JSON envelope, exit codes, and every error code above.