About

This CLI tool is used to manage projects built on top of the Puls Atlas Core Framework. Visit Puls to get in touch and learn more about what we do.

Installation

Requirements:

• Node.js 20 or newer

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
• Deploy
• Install
• Auth
• AI

Additional guides:

• Search
• Sync
• Services

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 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:

{
    "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:

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