> For the complete documentation index, see [llms.txt](https://docs.ai.neevcloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ai.neevcloud.com/getting-started/neev-cli.md).

# NeevCloud CLI

`neev-cli` is the command-line interface for NeevCloud. Use it to sign in, choose the organization and project you are working in, and manage sandboxes, agents and AI runtimes from a terminal or CI.

## Install

### macOS and Linux

```bash
curl -fsSL https://raw.githubusercontent.com/NeevCloudAI/neev-cli/main/install.sh | sh
```

The script detects your operating system and architecture, downloads the matching release archive, verifies its checksum, and installs `neev-cli` to `/usr/local/bin` — or `~/.local/bin` if that is not writable.

Pin a version, or change where it installs:

```bash
curl -fsSL https://raw.githubusercontent.com/NeevCloudAI/neev-cli/main/install.sh | NEEV_CLI_VERSION=v0.9.0 sh
curl -fsSL https://raw.githubusercontent.com/NeevCloudAI/neev-cli/main/install.sh | NEEV_CLI_INSTALL_DIR="$HOME/bin" sh
```

### Windows

There is no install script for Windows. Download `neev-cli_windows_amd64.zip` (or `neev-cli_windows_arm64.zip`) from the [latest release](https://github.com/NeevCloudAI/neev-cli/releases/latest), extract it, and add the folder to your `PATH`.

### Verify

```bash
neev-cli version
```

## Sign In

Sign in once with a Personal Access Token (`pat-nc-…`), which you mint in the console. Input is hidden when you are on a terminal.

```bash
neev-cli auth login
neev-cli auth status      # exits non-zero when signed out
neev-cli auth logout
```

For scripts and CI, avoid the interactive prompt:

```bash
echo "$NEEV_API_TOKEN" | neev-cli auth login --token-stdin
```

Or skip signing in and authenticate a single command through the environment:

```bash
export NEEV_API_TOKEN="pat-nc-..."
neev-cli org get
```

There is deliberately no flag that takes a token directly. A secret on the command line leaks into your shell history and the process list — use the prompt, `--token-stdin`, or the environment.

### You Do Not Have to Sign In

Signing in saves a session so you can stop thinking about credentials. It is a convenience, not a requirement. `NEEV_API_TOKEN` takes precedence over any saved session, so with it set every command works on its own — no session, no state on disk.

That is the right approach for CI, containers, and anywhere without an interactive terminal to type into:

```bash
export NEEV_API_TOKEN="pat-nc-..."
neev-cli sandbox get --org <org-id> --project <project-id>
```

Without a saved context, pass `--org` and `--project` on each command. Find the IDs with `neev-cli org get` and `neev-cli project get --org <org-id>`, or in the console as described in [Organizations and Projects](https://docs.ai.neevcloud.com/getting-started/org-and-project.md#find-your-organization-id-and-project-id).

## Choose an Organization and Project

Most commands need both. A context saves the pair so you stop passing flags.

```bash
neev-cli context get                                          # saved contexts, and the orgs and projects you can use
neev-cli context set dev --org <org-id> --project <project-id>   # save it and make it current
neev-cli context current
neev-cli context use <name>
neev-cli context delete <name>
```

`--org` and `--project` in `context set` take an ID or a name. An explicit `--org` or `--project` on any command overrides the current context.

If you only ever work in one organization and project, `neev-cli config set org-id <org-id>` and `neev-cli config set project-id <project-id>` save them as defaults without a named context.

## Two Credentials

The CLI uses two credentials that are not interchangeable. The Personal Access Token covers your account: organizations, projects, contexts, billing and AI runtimes. The sandbox API key (`sk-nc-…`) covers sandboxes and agents, and it is the only credential that runs `exec`, `fs`, `proxy` and `ssh-config`.

Save the API key with a context so sandbox and agent commands work without a PAT. The key is prompted for, or read from stdin when you pipe it:

```bash
neev-cli context set dev --org <org-id> --project <project-id> --sandbox-api-key
echo "$NEEV_API_KEY" | neev-cli context set ci --org <org-id> --project <project-id> --sandbox-api-key
```

`NEEV_API_KEY` in the environment overrides the saved key for a single command, and `--clear-sandbox-api-key` removes it from the context. See [Connecting to a Sandbox](https://docs.ai.neevcloud.com/agentic-studio/overview/development-and-connectivity/connecting-to-a-sandbox.md) for the full explanation.

If you have only the API key, sandbox and agent commands work but account commands fail:

```
Error: this command needs your account token: a sandbox API key covers sandbox and agent commands only. Run 'neev-cli auth login', or set NEEV_API_TOKEN
```

## Common Commands

Address a sandbox by its name. `get` lists sandboxes when you give no name, and `describe` shows one in full.

```bash
neev-cli sandbox create --name web --wait
neev-cli sandbox get
neev-cli sandbox describe web
neev-cli sandbox pause web
neev-cli sandbox resume web
neev-cli sandbox delete web
```

Run commands and move files:

```bash
neev-cli sandbox exec web -- python --version
neev-cli sandbox exec web -it -- bash
neev-cli sandbox fs write web src/app.py --in ./app.py
neev-cli sandbox fs get web src
neev-cli sandbox fs upload web ./site site
neev-cli sandbox fs download web site/out.log ./out.log
```

Snapshot, roll back and fork:

```bash
neev-cli sandbox snapshot create web --name before-upgrade
neev-cli sandbox snapshot get web
neev-cli sandbox rollback web --snapshot <snapshot-id>
neev-cli sandbox fork web --as web-copy
```

Serve an app at a public preview URL. Start the server in the sandbox first; `--wait` returns once it answers:

```bash
neev-cli sandbox port create web --port 3000 --wait
neev-cli sandbox port get web
neev-cli sandbox port delete web --port 3000
```

Anyone with a preview URL can open it without signing in, so share it with care.

Control which hosts a sandbox can reach. A new sandbox reaches none unless its template opens some; open hosts at create time, and edit the list later without a restart:

```bash
neev-cli sandbox create --name ci --allow github.com --allow pypi.org:443
neev-cli sandbox update ci --allow-add files.pythonhosted.org   # add a host, keep the rest
neev-cli sandbox update ci --allow-remove github.com
neev-cli sandbox egress get ci                                  # what it can reach
```

`--allow` replaces the whole list, `--allow-internet` opens everything, and `--deny-all` closes it. A host is a domain, a `*.` wildcard, an IP address or CIDR range, or an IPv6 address in brackets, optionally with `:PORT`.

Use `ssh` and your editor, or reach a host behind your VPN:

```bash
neev-cli sandbox ssh-config write web    # then: ssh web
neev-cli sandbox proxy web --allow-host staging.example.com:443
```

Tag sandboxes with labels and find them later:

```bash
neev-cli sandbox create --name e2e --label team=payments
neev-cli sandbox get -l team=payments
```

`neev-cli agent` has the same commands for agents, apart from `fork` and labels, and `neev-cli airuntime` and `neev-cli billing` cover AI runtimes and billing. Most commands take `-o json`, `-o yaml` or `-o name` for scripts, `--wait` to block until a change is done, and `get` takes `--watch` to keep printing changes.

## More Documentation

Run `neev-cli --help`, or `--help` on any subcommand, for the full list. The [neev-cli repository](https://github.com/NeevCloudAI/neev-cli) has a guide for each product and a reference for every command and flag:

| Guide                                                                                            | What it covers                                                            |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| [Getting started](https://github.com/NeevCloudAI/neev-cli/blob/main/docs/getting-started.md)     | Install to your first sandbox, plus a CI recipe and troubleshooting       |
| [Sandboxes](https://github.com/NeevCloudAI/neev-cli/blob/main/docs/sandboxes.md)                 | Commands, files, preview URLs, egress, SSH, snapshots, labels and metrics |
| [Agents](https://github.com/NeevCloudAI/neev-cli/blob/main/docs/agents.md)                       | Ready-made coding agents such as Claude Code                              |
| [AI runtimes](https://github.com/NeevCloudAI/neev-cli/blob/main/docs/ai-runtimes.md)             | GPU environments                                                          |
| [Command reference](https://github.com/NeevCloudAI/neev-cli/blob/main/docs/command-reference.md) | Every command and flag                                                    |

## Setting Up with a Coding Agent

If you would rather have your coding agent install and configure this for you, see [Set Up with Your Coding Agent](https://docs.ai.neevcloud.com/agentic-studio/overview/development-and-connectivity/agent-onboarding.md).

To have a coding agent such as Claude Code, Cursor or Codex use `neev-cli` for a task, point it at [Use neev-cli from an AI agent](https://github.com/NeevCloudAI/neev-cli/blob/main/docs/ai-agents.md). It has prompts to paste into the agent, and the rules the agent follows: running without a terminal, confirming before it deletes or spends, and cleaning up.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ai.neevcloud.com/getting-started/neev-cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
