Docs/Quickstart/Install the CLI

Install the CLI

The atlas command is how you create services, push deployments and read logs. It runs on macOS, Linux and Windows, and needs Node 20.9 or newer.

Install

Install the package globally, then sign in. The sign-in step writes a token to ~/.atlas/credentials and prints the workspace it resolved.

shell

npm install -g atlas-cli
atlas login
atlas init my-service

atlas init writes an atlas.config.js file into the current directory and adds a .atlasignore beside it. Neither file is overwritten if it already exists — pass --force when you want a clean one.

Note

If your team installs tooling per project rather than globally, add atlas-cli as a dev dependency and call it through npx atlas. Every command below behaves identically.

Command options

These flags apply to atlas init and, with the exception of --template, to atlas deploy as well.

Name	Type	Default	Description
--region	string	eu-west	Placement region for the service. Changing it after the first deployment recreates the service.
--runtime	string	node20	Runtime image. Accepts `node20`, `node22`, `python3.12` and `go1.23`.
--template	string	minimal	Starter to scaffold from. Run `atlas templates` for the current list.
--profile	string	default	Named credential profile to read from the local credentials file.
--dry-run	boolean	false	Report the planned changes and exit without touching the workspace.

If the install fails

A permissions error on the global install usually means npm's prefix points somewhere your user cannot write. Set a writable prefix rather than running the installer with elevated privileges. If atlas login hangs, run it with --device-code and paste the code shown in the terminal.

Configure the project

The generated config exports a plain object. Paths are resolved relative to the config file, so a monorepo can keep one config per package without absolute paths.

atlas.config.js

const { defineService } = require('atlas-cli/config');
const routes = require('./src/routes');

module.exports = defineService({
  name: 'my-service',
  runtime: 'node20',
  entry: './src/index.js',
  region: 'eu-west',
  routes,
  build: { command: 'npm run build', output: './dist' },
  env: { LOG_LEVEL: 'info', QUEUE_PREFIX: 'my-service' }
});

Deploy the scaffold

Nothing needs editing before the first deploy. Take the service through the whole flow once, then start changing it:

Run atlas init my-service and pick a region when prompted.
Change into the new directory and run npm install.
Start it locally with atlas dev and confirm the health check passes.
Run atlas deploy --env staging and wait for the build to finish.
Tail the first requests with atlas logs --follow.

Warning

Deleting a service also deletes its secrets and its queue bindings. There is no undo and no retention window — export anything you need with atlas secrets export first.

Next steps

QuickstartCreate your first service API referenceServices endpoint

Last updated 6 March 2026

Was this page helpful?