---
title: CLI Installation
---

The ZevCloud CLI lets you deploy, manage services, and view logs from your terminal.

## What the CLI does

The CLI covers the full lifecycle of a ZevCloud service from your terminal:

- **`zevcloud init`** — interactive service creation from your current directory. Detects whether you have a GitHub remote or not and picks the right source mode automatically: GitHub-source for repos with a remote, direct terminal upload for fresh projects without one. Walks you through project + plan + framework + confirmation, then triggers your first deploy.
- **`zevcloud deploy <serviceId>`** — redeploy an existing service. For GitHub-source services it pulls latest from the configured branch. For upload-source services it re-tars your current directory and uploads a fresh build context. The CLI knows which mode each service is in and does the right thing.
- **Service operations** — view runtime logs (`logs`), manage environment variables (`env`), restart (`restart`), stop (`stop`).
- **Team / project management** — list teams, projects, services. Switch between teams in the same shell with `team switch`.

If you're new to ZevCloud, start with [`zevcloud login`](/cli/auth) and then [`zevcloud init`](/cli/commands#zevcloud-init) — both are interactive and walk you through everything.

## Install

```bash
npm install -g @zevcloud/cli
```

Or use without installing:

```bash
npx @zevcloud/cli login
```

## Authentication

Generate an API key from [Dashboard → Settings → API Keys](https://console.zevcloud.net/settings?tab=api-keys). Pick the scope that matches what the CLI needs to do — `deploy` is right for most CI and agent workflows; `full` is equivalent to a human admin. See [Authentication](/cli/auth) for the scope hierarchy and what each one allows.

Then authenticate:

```bash
zevcloud login
```

Paste your API key when prompted. The CLI validates it against the API and stores it locally.

## Verify

```bash
zevcloud whoami
```

Shows the active team, the API URL it's pointing at, and a partial key fingerprint. If you've configured more than one team it also lists the others so you know what's available to switch to.

You can also confirm the CLI is installed and check for updates:

```bash
zevcloud version
```

This prints the installed version, the latest version on npm (when known), and your Node and platform info. Useful for bug reports.

## Quick start

The fastest way to ship code: `cd` into your project directory and run `zevcloud init`. It detects whether you have a GitHub remote and walks you through the rest interactively — pick a project, plan, framework, and the CLI handles the first build and deploy.

```bash
# From inside your project directory
cd my-app
zevcloud init
```

Already deployed and want to push an update?

```bash
# List your services to find the id
zevcloud services

# Redeploy (the CLI handles GitHub-pull or terminal-upload automatically
# based on how the service was created)
zevcloud deploy <serviceId>

# View logs
zevcloud logs <serviceId> -f
```

## Configuration

Set a custom API URL (for self-hosted or sandbox):

```bash
zevcloud config --api-url https://zevcloud-apisandbox.zevop.net/v1
```

The URL must use HTTPS. The CLI rejects plaintext HTTP endpoints to keep API keys off the wire in cleartext.

## CI and AI agents

For non-interactive environments where storing an API key on disk is undesirable, set credentials via environment variables instead:

```bash
export ZEVCLOUD_API_KEY=sk_live_...
export ZEVCLOUD_TEAM_ID=<your-team-id>

zevcloud deploy <serviceId>
```

When `ZEVCLOUD_API_KEY` is set the CLI uses it for every command and never reads or writes the on-disk credential store. Pair it with `ZEVCLOUD_TEAM_ID` so the team-id header is set explicitly. This is the right pattern for GitHub Actions, GitLab CI, and AI agent runners.

## Updates

The CLI checks the npm registry once every 24 hours for a newer version. If one is available, you'll see a small notice after your command completes — no extra action required to receive it. To disable the check, set `ZEVCLOUD_DISABLE_UPDATE_CHECK=true`.

## Next Steps

- [Authentication details](/cli/auth)
- [Full command reference](/cli/commands)