# Next CLI

> Use the NexHost Git command-line interface to work with hosted repositories.

Source: https://nexthomelabs.com/docs/cli
Markdown: https://nexthomelabs.com/docs-md/cli
Slug: cli
Section: Operate
Last updated: 2026-08-30
Reading time: 6 min read

---

# Next CLI

The Next CLI is NexHost’s hosted Git command-line interface. Repository access for a NexHost workspace is managed through the **Next CLI** and the dashboard’s Repositories surface; after authentication the CLI delegates source-control operations to the standard Git workflow — `add`, `commit`, `push`, `pull` — rather than introducing a second mental model for "how Git works."

It is intentionally scoped: the CLI **manages repository authentication and delegates source-control operations to the standard Git workflow**. It does **not** trigger deployments, stream service logs, or set deployment environment variables — those remain dashboard operations, reviewed and triggered on the service itself.

## What the CLI is — and is not

| The CLI handles | You do in the dashboard |
| --- | --- |
| Authenticating a workspace session for Git | Triggering or reviewing deployments |
| Listing and creating hosted repositories | Reading per-deployment build output and release stages |
| Cloning, committing, pushing, pulling, and syncing | Setting environment variables and health paths |
| Diagnosing local Git and auth setup via `doctor` | Wiring a repository to a service source |

Understanding this boundary keeps the repository change ("I pushed new code") and the release decision ("I told NexHost to deploy it") distinct — a push does not by itself change a live release.

## Install

Download the current package from [CLI Downloads](/cli/downloads). On Debian or Ubuntu, install the downloaded package with:

```bash
sudo apt install ./next-cli_0.1.0_all.deb
```

That `.deb` lands the platform binaries on the `PATH`. Other download formats for different operating systems are listed on the same downloads page when available.

The platform command names are `next`, `nexhost`, and `nex` — all aliases for the same binary. `next` is the first-class source-control command. Before you alias or adopt it, run `which -a next` (or `where next` on Windows tooling) and confirm you do **not** overwrite an existing `next` binary from a local framework installation without checking your local environment. A Next.js project invoked via `next` on a developer machine conflicts is unwelcome; the error or wrong code path can be hard to trace if you inadvertently shadow it.

> [!TIP]
> Prefer to run `next --version` and `next doctor` immediately after install. A clean `doctor` output on a fresh workspace proves path, credential helper, and Git wiring before you involve real source.

## Sign in and work with a repository

The typical flow is login, inspect repositories, clone one, edit, commit, and push — identical to any Git host after the first command:

```bash
next login --team YOUR_WORKSPACE
next repo list
next clone YOUR_WORKSPACE/YOUR_REPOSITORY
cd YOUR_REPOSITORY
next status
next add .
next commit -m "Initial commit"
next push
```

Each step in detail:

1. **`next login --team YOUR_WORKSPACE`** — authenticates your local session to the workspace you intend to operate in. Prefer this form when you are at your own workstation.
2. **`next repo list`** — lists repositories the authenticated principal can see in that workspace. This confirms scope before you clone.
3. **`next clone YOUR_WORKSPACE/YOUR_REPOSITORY`** (and `next init` for a new local directory you want to turn into a hosted repository) — materializes the workspace-hosted remote into a local Git directory with a credential-safe remote URL.
4. **`next status`, `add`, `commit`, `push`, `pull`, `sync`** — operate on the checked-out branch. Authentication is preserved by the CLI across these commands; the remote URL itself does not expose the credential.

You can also use these authentication variants when the situation calls for them:

- `next login --device --team YOUR_WORKSPACE` — **device flow** for browsers or constrained terminals. The CLI prints a code and flow URI; authorize in the browser that *is* authenticated to the workspace.
- `next login --pat` — **personal access token** flow. Enter a token via the secure prompt — do not paste a token into shell history or draft messages where it may linger in logs. Rotate tokens that were ever echoed or typed in plain view.

> [!WARNING]
> Never embed a PAT or session credential in a remote URL and never commit a token to the repository. NexHost’s credential handling is designed to keep the remote URL credential-free — `next doctor` will confirm it.

## Available commands

| Command | Purpose | Typical next step |
| --- | --- | --- |
| `login`, `logout`, `whoami` | Manage the current hosted-Git session: authenticate, end the session, or confirm who you are | After `login`, `next repo list`; after `logout`, `next login --team …` before you clone |
| `repo list`, `repo create` | View or create hosted repositories in the workspace (`repo create` can carry `--private` to set visibility) | `next clone YOUR_WORKSPACE/<name>` or `next doctor` when the local wiring needs checking |
| `init`, `clone` | Start or retrieve a repository — `init` to wire a fresh local directory, `clone` to fetch an existing one | `next status`, then the `add → commit → push` cycle |
| `status`, `add`, `commit`, `push`, `pull`, `sync` | Run familiar source-control operations through Git plumbing with the workspace session applied | Push to publish, `pull`/`sync` to incorporate teammates’ changes before branching |
| `doctor` | Check the local CLI and Git setup — credential helper, PATH, Git versioning | Run whenever auth fails or a clone/pull reports credential or remote problems |

After you push source, **connect that repository to a NexHost service in the dashboard** to create a deployment. During **New Project**, choose the source that corresponds to your hosted repository, pick the branch, confirm the root directory, and review build and start settings. The Git push produced the artifact source; only the dashboard action turns it into a recorded release.

## Common workflows

**Create, push, and wire:**

```bash
next login --team YOUR_WORKSPACE
next repo create my-service --private
next clone YOUR_WORKSPACE/my-service
cd my-service
# edit, test locally
next add .
next commit -m "Ship the service"
next push
# Dashboard → New Project → choose NexHost Git → pick my-service + branch → set build/start → Deploy
```

**Doctor and repair:**

```bash
next doctor         # credential helper & Git wiring
next whoami         # confirm session identity
next logout
next login --team YOUR_WORKSPACE
```

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `not logged in` / auth on clone | Session expired, wrong `--team`, or unauthenticated terminal | `next whoami`, then `next login --team YOUR_WORKSPACE` or `next login --device --team …` on headless sessions |
| `remote: access denied` | Repository exists in a different workspace or visibility is wrong | Verify the `YOUR_WORKSPACE/REPOSITORY` label in the dashboard Repositories screen matches what you typed |
| `command not found: next` shadows Next.js | PATH ordering or shadow of the framework binary | Check `which -a next`; invoke the platform binary via its full name (`nexhost`) or a shell that disambiguates |

## Related documentation

- [NexHost Git](/docs/git) — the hosted repository side: dashboard creation, push semantics, and connecting to a service.
- [API Access and Availability](/docs/api) — what is not a public programmatic surface and the support path for integrations.
- [Your First Deployment](/docs/getting-started/your-first-deployment) — numbered dashboard path from source to verified URL.