@puls-atlas/cli/README.md

The Puls Atlas CLI tool for managing Atlas projects

## About

This CLI tool is used to manage projects built on top of the Puls Atlas Core Framework. Visit [Puls](https://puls.be) to get in touch and learn more about what we do.

## Installation

Requirements:

- Node.js 20 or newer

```bash
npm install -g @puls-atlas/cli
```

## Usage

All commands must be run in the root of a Puls Atlas project.
The following commands should get you started:

- `atlas -v` or `atlas --version` - Display the current version of the CLI tool.
- `atlas -h` or `atlas --help` - Display the help menu with all available commands.
- `atlas <command> -h` or `atlas <command> --help` - Display the help menu for a specific command.

## Documentation

Command guides:

- [Start](./docs/start.md)
- [Deploy](./docs/deploy.md)
- [Install](./docs/install.md)
- [Auth](./docs/auth.md)
- [AI](./docs/ai.md)

Additional guides:

- [Search](./docs/search.md)
- [Sync](./docs/sync.md)
- [Services](./docs/services.md)

Additional command groups are available through the CLI, including `init`, `misc`, and `export`.
Use `atlas --help` or `atlas <command> --help` for the full command surface when a dedicated guide is not available yet.

## Atlas AI consumer wiring

Atlas consumer projects can now generate a local Atlas AI bootstrap layer instead of relying on one large repo-local instructions file.

The relevant commands are:

- `atlas ai init` to create the managed Atlas AI files for a project that does not have them yet
- `atlas ai sync` to refresh those files after Atlas package installs or updates
- `atlas ai verify` to detect drift before larger Atlas-specific work or in CI

The generated consumer file set now consists of:

- `.github/agents/atlas.agent.md`
- `.github/agents/atlas-framework.agent.md`
- `.github/agents/atlas-frontend.agent.md`
- `.github/agents/atlas-api.agent.md`
- `.github/agents/atlas-functions.agent.md`
- `.github/agents/atlas-review.agent.md`
- `.github/agents/atlas-prototype.agent.md`
- `.github/copilot-instructions.md`
- `.atlas/ai/context-snapshot.json`
- `.atlas/ai/context-lock.json`

See [AI](./docs/ai.md) for the discovery order, file responsibilities, and override strategy for consumer projects.

## Atlas Search deploy identities

`atlas search deploy` and `atlas search provider deploy` use two different Google Cloud identities that are easy to confuse:

- the Cloud Run runtime service account used by Atlas search services and the static backfill job
- the Cloud Run service agent that imports container images from Artifact Registry during deployment

### Runtime service account default

If `search/config.json` does not set `deploy.cloudRun.serviceAccountEmail`, the CLI now defaults the Atlas search Cloud Run runtime identity to the App Engine default service account for the target project:

```json
{
    "deploy": {
        "cloudRun": {
            "serviceAccountEmail": "<project-id>@appspot.gserviceaccount.com"
        }
    }
}
```

This default is used for:

- the static `atlas-search-backfill` Cloud Run Job Terraform payload
- provider-runtime Terraform payloads created by `atlas search provider deploy`

Set `deploy.cloudRun.serviceAccountEmail` explicitly if a project needs a different runtime identity.

### Cross-project Artifact Registry access

When Atlas search deploys Cloud Run services or jobs from images stored in the shared `puls-atlas-core` Artifact Registry, the runtime service account is not the identity that pulls the image during deployment.

For cross-project image imports, Google Cloud Run requires Artifact Registry access for the service agent of the consumer project:

```text
service-<project-number>@serverless-robot-prod.iam.gserviceaccount.com
```

`atlas search deploy` now bootstraps this automatically for the shared Atlas runtime repository when the executing identity has permission to update Artifact Registry IAM in `puls-atlas-core`.

The deploy flow also resolves the configured runtime image tags to immutable digests before Terraform and Cloud Run updates are applied, so each deploy targets the exact Atlas Core image revision that matched the selected tag at deploy time.

In practice this means:

- grant `<project-id>@appspot.gserviceaccount.com` whatever runtime access the customer project needs to shared Atlas Core resources
- let `atlas search deploy` ensure `service-<project-number>@serverless-robot-prod.iam.gserviceaccount.com` has read access to the shared Artifact Registry repository so Cloud Run can import the image during deploy