@newly/cli

v0.1.2

Published

5 days ago

Develop, provision, and deploy Newly backends from your terminal

0High
0Medium
0Low

timothylindblom

ci-lifecycle-test

newly CLI

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

Install

npm i -g @newly/cli

Installs the newly binary. Requires Node ≥ 20.

Quick start

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
newly services list      # inspect backend services
newly email status       # inspect Newly Email setup

Auth

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

The token expires. Re-run newly login when commands report you're logged out.

Project linking

Most 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 anything.
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. |

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

Only projects on the Newly backend stack are CLI-deployable. Run newly stack to check. Other projects must be deployed from the Newly web app.

Commands

`newly pull [project-id]`

Download the project working tree (app + backend) into the current directory and link it.

--branch <name> — pull a specific branch (default: project's active branch).
--force — overwrite a non-empty directory (discards local changes).

`newly create [name]`

Create a new backend-only project here, scaffold backend/, and link the directory. Provisions the dev backend by default.

--no-provision — create without provisioning.

Run in a directory with no backend/ and no existing link.

`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.

--project <id>

`newly stack`

Show which backend stack the project uses and whether it's CLI-deployable.

--project <id>

`newly deploy`

Provision the backend if needed, then deploy.

--env <dev|prod> (default dev)
--region <region> — region for first-time dev provisioning (default auto)
--project <id>
--service <names> — comma-separated service names from backend/newly.services.json
--git-sha <sha> — prod git revision to deploy (default HEAD)
--yes — skip the prod confirmation prompt

`newly services list`

List backend services from backend/newly.services.json.

--env <dev|prod> (default dev) — used for rendered public URLs
--project <id> — include expected public URLs for this project

`newly logs`

Tail backend service logs. Dev only.

--service <api|auth> (default api)
-n, --lines <n> (default 200)
--since <duration> — relative window, e.g. 30s, 5m, 2h
--start <iso> / --end <iso> — absolute window (ISO 8601)
--project <id>

`newly secrets list`

List the secret keys set for a service (names only). Dev only.

--service <api|auth> (default api)
--project <id>

`newly secrets set <key> <value>`

Set a backend secret. Dev only. Redeploy to apply.

--service <api|auth> (default api)
--project <id>

`newly db url`

Print a readonly URL for the Newly DB. Dev only.

--project <id>

`newly email status`

Show Newly Email configuration for the API service. Dev only.

--project <id>

`newly email test`

Send a test email through the deployed API service. Dev only.

--to <email> — recipient address
--from <email> — optional sender; defaults to the backend sender setting
--subject <subject>
--text <text>
--html <html>
--project <id>

Dev mode

newly-dev is a convenience wrapper that points credentials at ~/.newly-dev so dev and prod credentials never collide. The prod newly binary still defaults to https://newly.app and ~/.newly/credentials, untouched.

Headless login

For CI and dev modal-backend deploys where no web app is running to mint a CLI token, skip the browser entirely:

newly-dev login \
  --api-url https://your-dev-modal.modal.run/api \
  --token <jwt> \
  --expires-in 86400

--expires-in is seconds. The same flags work on the prod newly binary.

Env vars

| Var | Effect | |---|---| | NEWLY_HOME | Credentials directory. Explicit value always wins. | | NEWLY_DEV_HOME | Credentials directory used by newly-dev (default: ~/.newly-dev). | | NEWLY_APP_URL | Default for --app-url at module load. | | NEWLY_DEV_APP_URL | When set, newly-dev surfaces this as NEWLY_APP_URL. |

Typical dev workflow

# 1. Deploy a personal dev modal-backend.
cd modal-backend
uv run ./deploy.sh --terminate

# 2. Grab the deployed URL, then log the dev CLI in headlessly.
newly-dev login --api-url https://your-dev-modal.modal.run/api --token <jwt>

# 3. Use newly-dev the same way as newly.
newly-dev create my-test
newly-dev status
newly-dev deploy

Files

~/.newly/credentials — session token (mode 600). Override the directory with NEWLY_HOME.
~/.newly-dev/credentials — newly-dev session token. Override the directory with NEWLY_DEV_HOME.
.newly/project.json — per-directory project link.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

newly CLI

Install

Quick start

Auth

Project linking

Dev vs prod deploys

Commands

newly pull [project-id]

newly create [name]

newly link <project-id>

newly status

newly stack

newly deploy

newly services list

newly logs

newly secrets list

newly secrets set <key> <value>

newly db url

newly email status

newly email test