> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newly.app/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Develop, provision, and deploy your Newly backend from the terminal

The `newly` CLI lets you pull your project's backend code, deploy it, and manage logs, secrets, and the database from your terminal.

<Note>
  The CLI works with **Liquid Backend** projects. Run `newly stack` to check if a project is supported.
</Note>

## Install

```bash theme={null}
npm i -g @newly/cli
```

Requires **Node ≥ 20**.

## Quick start

```bash theme={null}
newly login              # authenticate in the browser
newly pull <project-id>  # download project code + link this directory
# edit code…
newly deploy             # deploy to dev
newly deploy --env prod  # ship to prod
```

## Auth

```bash theme={null}
newly login          # opens a browser, stores a session token in ~/.newly/credentials
newly login --manual # paste the credential instead of using the browser callback
newly logout         # delete stored credentials
```

Re-run `newly login` when a command reports your session has expired.

## Project linking

Commands target the project linked to the current directory, so you don't pass `--project` every time.

* `newly pull <project-id>` and `newly create` link automatically.
* `newly link <project-id>` links a directory without downloading code.
* Pass `--project <id>` to any command to override the link.

## Dev vs prod deploys

|                           | Source                   | Notes                                                                                                                     |
| ------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `newly deploy` (dev)      | **Your local code**      | Fast inner loop. Ephemeral — overwritten the next time the project is built on the Newly platform. Not a rollback target. |
| `newly deploy --env prod` | **Project code at HEAD** | Runs server-side, ignores local edits. Push your changes into the project first.                                          |

<Warning>
  `newly deploy --env prod` deploys the project's committed code, **not** your local files. Push your changes into the project before deploying to prod.
</Warning>

Prod actions prompt for confirmation. Pass `--yes` to skip it in scripts.

## Commands

### `newly pull [project-id]`

Download the project code into the current directory and link it.

| Option            | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `--branch <name>` | Pull a specific branch (default: the project's active branch). |
| `--force`         | Overwrite a non-empty directory (discards local changes).      |

### `newly create [name]`

Create a project, provision its production database, scaffold `backend/`, select
production, and deploy the starter backend. Run this in a directory with no
`backend/` and no existing project link.

| Option        | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| `--no-deploy` | Provision and select production without deploying the starter backend. |

Production starts with 2 GiB of storage.

### `newly link <project-id>`

Link the current directory to a project without downloading code.

### `newly status`

Show dev and prod status, service URLs, deployed SHA, and last error. Accepts `--project <id>`.

### `newly stack`

Show which backend stack the project uses and whether it's CLI-deployable. Accepts `--project <id>`.

### `newly up`

Provision the backend (if needed) and deploy.

| Option              | Default       | Description                        |
| ------------------- | ------------- | ---------------------------------- |
| `--env <dev\|prod>` | `dev`         | Target environment.                |
| `--region <region>` | `us-central1` | GCP region for dev provisioning.   |
| `--project <id>`    | linked dir    | Target project.                    |
| `--yes`             | —             | Skip the prod confirmation prompt. |

### `newly deploy`

Deploy the backend.

| Option              | Default    | Description                        |
| ------------------- | ---------- | ---------------------------------- |
| `--env <dev\|prod>` | `dev`      | Target environment.                |
| `--project <id>`    | linked dir | Target project.                    |
| `--yes`             | —          | Skip the prod confirmation prompt. |

### `newly logs`

Tail backend service logs. **Dev only.**

| Option                          | Default    | Description                              |
| ------------------------------- | ---------- | ---------------------------------------- |
| `--service <api\|auth>`         | `api`      | Service to tail.                         |
| `-n, --lines <n>`               | `200`      | Number of lines.                         |
| `--since <duration>`            | —          | Relative window, e.g. `30s`, `5m`, `2h`. |
| `--start <iso>` / `--end <iso>` | —          | Absolute window (ISO 8601).              |
| `--project <id>`                | linked dir | Target project.                          |

### `newly secrets list`

List the secret keys set for a service (names only). **Dev only.** Accepts `--service <api|auth>` (default `api`) and `--project <id>`.

### `newly secrets set <key> <value>`

Set a backend secret. **Dev only.** Redeploy to apply. Accepts `--service <api|auth>` (default `api`) and `--project <id>`.

### `newly db url`

Print a readonly Postgres URL for the backend database. **Dev only.** Accepts `--project <id>`.

## Files

| Path                   | Purpose                                                               |
| ---------------------- | --------------------------------------------------------------------- |
| `~/.newly/credentials` | Session token (mode `600`). Override the directory with `NEWLY_HOME`. |
| `.newly/project.json`  | Per-directory project link.                                           |