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.

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.

Deploy the scaffold

The scaffolded service is deployable as generated. Work through it once end to end before you change anything:

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

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 config file exports a plain object. Every path in it is read relative to the file itself, which keeps monorepo packages free of absolute paths.

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' }
});

Command options

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

Where to go next