Install & Authenticate

What you'll be able to do after this module

By the end you'll have the CLI installed, your account connected, and a project linked — ready to run every command in the rest of this path.

Before you start

You need:

• Node.js 18 or later. Check yours:

  node --version

  If you're below 18, update via your version manager (nvm install 18 && nvm use 18) or nodejs.org.

• A Skytells account. Free at console.skytells.ai.

Install

npm install -g @skytells/cli

Confirm it worked:

skytells --version
# 1.0.0

skytells --help

Authenticate

The CLI needs to know who you are. There are two ways to do this. Start with the device flow — it's the safest option for developer laptops.

Option A — Device flow (recommended for laptops)

skytells login

What happens:

1. The CLI contacts Skytells and gets a one-time code.
2. Your browser opens to console.skytells.ai/device.
3. You enter the code and approve access.
4. The CLI receives your token and saves it to ~/.config/skytells/credentials.json.

You'll see something like:

⠋ Initiating device authorization...

  Your device code is: ABCD-1234

  Open this URL in your browser to authorize:
  https://console.skytells.ai/device

  Waiting for authorization...
✔ Authenticated successfully!
  Credentials saved to ~/.config/skytells/credentials.json

The authorization window is valid for 15 minutes. If it times out, just run skytells login again.

Option B — Personal access token (recommended for servers and CI)

If you're setting up a server, a container, or a CI environment, use a token instead:

1. Go to console.skytells.ai/settings/tokens.
2. Click Create Token, choose a name, pick the minimum scopes you need, and confirm.
3. Copy the token immediately — it starts with sk_pat_ and is shown only once.

Then paste it into the CLI:

skytells login --token
# Paste your token when prompted

Or set it as an environment variable (covered in detail in Module 4):

export SKYTELLS_TOKEN=sk_pat_your_token_here

Verify you're signed in

skytells whoami

This prints your user ID, name, and auth status. If something is wrong, login again.

Token scopes

When you log in with --scopes, you limit what the token can do. This matters for shared environments and CI pipelines — never give a token more access than it needs.

The default when you run skytells login with no --scopes flag: inference, projects.read, deployments.read, account.read.

For a deployment-focused CI workflow, add deployments.write:

skytells login --scopes inference,projects.read,deployments.read,deployments.write

Link a project

Most CLI commands operate in the context of a specific project. You tell the CLI which project to use by linking its access key.

Where to find the access key:

1. Open console.skytells.ai.
2. Select the project you want to work with.
3. Go to Settings inside that project.
4. Copy the access key — it starts with sk_proj_.

Then link it:

skytells link sk_proj_your_access_key_here

The CLI stores the key alongside your user token. From this point on, commands like skytells apps ls, skytells deploy, and skytells logs all know which project to target.

Confirm the link:

skytells project

You'll see:

Project: my-project
  ID:           abc123
  Type:         production
  Network Mode: public
  Description:  My production project
  Created:      2026-01-15

Credential storage

Your credentials live at:

~/.config/skytells/credentials.json

The file is created with 0600 permissions (only your user can read it). It holds your personal access token and your linked project access key.

To use a different storage location (useful for shared systems):

export SKYTELLS_CONFIG_DIR=/custom/path

To sign out:

skytells logout
# or skip the confirmation prompt:
skytells logout --force

How precedence works

When the CLI looks for credentials, it follows this order — highest wins:

1. Command-line flags (e.g., --token)
2. Environment variables (SKYTELLS_TOKEN, SKYTELLS_ACCESS_KEY)
3. Stored credentials (~/.config/skytells/credentials.json)

This means you can always override the stored credentials with an environment variable in CI, without touching the file.

Quick troubleshooting

What you can now do

You're authenticated and have a project linked. In the next module you'll create apps and manage the app lifecycle from the terminal.

Up next: Module 2 — Projects & Apps →