---
title: "Package ids and folders"
url: "https://docs.alisx.com/reference/dbd/package-ids-and-folders/"
---
# Package ids and folders

How a package id names a service, where its folders live on disk, and how the CLI resolves the organisation, product and service from the working directory.

## Package id format

```text
<org>.<product>.<path>.<vN>
```

| Part | Meaning | Example |
|---|---|---|
| `<org>` | The build environment (organisation) id | `acme` |
| `<product>` | The product id | `sh` |
| `<path>` | The service path, one or more dot-separated segments | `orders`, `internal.api` |
| `<vN>` | The service version, `v` plus a number | `v1`, `v2` |

## Mapping

| Package id | Resource name | Build folder | Define folder |
|---|---|---|---|
| `acme.sh.orders.v1` | `organisations/acme/products/sh/neurons/orders-v1` | `~/alis.build/acme/build/sh/orders/v1` | `~/alis.build/acme/define/acme/sh/orders/v1` |
| `acme.sh.internal.api.v2` | `organisations/acme/products/sh/neurons/internal-api-v2` | `~/alis.build/acme/build/sh/internal/api/v2` | `~/alis.build/acme/define/acme/sh/internal/api/v2` |

- The service id is the path with `/` replaced by `-`, followed by the version.
- The protobuf `package` statement equals the package id: `package acme.sh.orders.v1;`.
- The generated Go package for a `v1` service is imported as `alis.build/<org>/<product>/<path>`, for example `alis.build/acme/sh/orders`.
- The build folder holds the implementation, its Dockerfiles and `infra/`. The define folder holds the `.proto` files.

## Repositories on disk

| Repository | Path | Contents |
|---|---|---|
| Definitions repo (one per build environment) | `~/alis.build/<org>/define` | `<org>/<product>/<path>/<vN>/*.proto` for every service of every product |
| Build repo (one per product) | `~/alis.build/<org>/build/<product>` | `<path>/<vN>/` per service, and `.alis/.env` for local runs |

`alis clone <org>.<product>` creates both; a repository already on disk is fast-forward pulled.

## Context resolution

`alis context view --json` prints what the CLI resolves from the working directory: `organisation`, `product`, `packageId`, `serviceFolder`, `defineFolder` and the product's `environments[]` with `id`, `displayName`, `status`, `production` and `projectId`. Sections that cannot be resolved are omitted with the reason under `notes`.

| Working directory | What can be omitted |
|---|---|
| Inside `~/alis.build/<org>/build/<product>/<path>/<vN>` | The package id: `alis build`, `alis define`, `alis deploy`, `alis packages install` act on that service. |
| Inside `~/alis.build/<org>/build/<product>` | The `<org>.<product>` reference: `alis product view`, `alis environment list`. Dot-references fill right-aligned, so `alis environment refresh <env-id>` expands to `<org>.<product>.<env-id>`. |
| Outside `~/alis.build` | Nothing; pass the full reference. |

`--cwd <dir>` runs a command as if from that directory without changing the shell.

## Commits and branches

| Command | Commit used |
|---|---|
| `alis define` | The latest pushed commit of the definitions repo; `--commit <sha>` pins one. |
| `alis build` | The latest pushed commit touching the service folder on the checked-out branch; `--branch <branch>` chooses another pushed branch; `--commit <sha>` pins one. A detached checkout must pass `--branch`. |

Unpushed work is never built or defined.

## Inside a workstation

A workstation's CLI resolves only its own build environment. `ALIS_BUILD_SHELL=1`, `ALIS_ORGANISATION=<org>` and `ALIS_WORKSTATION=organisations/<org>/workstations/<id>` are set; a command on another build environment exits 1 with "this workstation is locked to build environment ...". `alis workstation url <port>` prints the address of a port on the machine from `ALIS_PORT_URL_TEMPLATE`.