Skip to content
Sprigr

Deploy CLI

The @sprigr/cli package is a command-line tool for deploying websites to Sprigr Teams hosting from your terminal or a CI pipeline. Most people let an agent build and deploy sites through chat (see Builds and Deployments), but the CLI is there when you want to deploy your own files directly, script deployments, or recover a site’s source.

Everything the CLI deploys ends up in the same place as an agent-driven or portal deploy: a build, a numbered deployment, and a live site with full version history and rollback.

Installing

Section titled “Installing”

The CLI is published to npm and requires Node.js 20 or newer.

Terminal window
npm install -g @sprigr/cli

You can also run it without installing:

Terminal window
npx @sprigr/cli --help

The command is called sprigr. Run sprigr --help at any time to see the full command list.

Authenticating

Section titled “Authenticating”

The CLI needs a Sprigr API key to talk to your organisation. There are two ways to provide one.

Section titled “Browser sign-in (recommended)”

sprigr login runs a browser-based device-authorization flow, so you never have to copy a key by hand:

  1. Run the login command

    Terminal window
    sprigr login

  2. Approve in your browser

    The CLI prints a URL and a short code, and tries to open the URL for you. Sign in to the portal if you are not already, confirm the code matches, and approve the request. Codes are valid for 10 minutes.

  3. You are logged in

    Once you approve, the CLI mints a fresh API key and saves it to ~/.config/sprigr/credentials.json (readable only by you). Subsequent commands pick it up automatically.

On a headless machine (CI, SSH), pass --no-browser so the CLI only prints the URL instead of trying to launch a browser.

Run sprigr whoami to confirm which organisation the next command will target, or sprigr logout to remove the saved credentials.

API key

Section titled “API key”

You can also create an API key in the portal under Settings → API keys and provide it directly:

Terminal window
export SPRIGR_API_KEY=sk_...

Any command also accepts --api-key <key> to override the environment variable for a single call.

Working with more than one organisation

Section titled “Working with more than one organisation”

If you deploy to more than one organisation (or to separate staging and production environments), use named profiles so their credentials do not overwrite each other:

Terminal window
sprigr login --profile staging
sprigr login --profile prod


sprigr --profile staging deploy my-site --dir ./public
SPRIGR_PROFILE=prod sprigr deploy my-site --dir ./public

Each profile stores its own key and endpoint. sprigr whoami --all lists every profile you are logged in to.

Deploying a site

Section titled “Deploying a site”

sprigr deploy bundles a directory and deploys it as a new build for an existing website. You need the website’s ID, which you can get from the site’s page in the portal.

Terminal window
# Deploy a static site
sprigr deploy <siteId> --dir ./public


# Deploy a framework app
sprigr deploy <siteId> --dir ./build --framework next

The --framework flag accepts static (the default), next, astro, and remix, matching the frameworks the hosting build farm supports (see Builds and Deployments). For a static deploy the directory must contain an index.html.

The CLI tarballs your directory, starts a build, and then polls until the build reaches a terminal state, printing the status as it changes. On success it prints the deployment ID. If your plan’s limits are reached, the deploy fails with a message pointing you to the portal to upgrade or check usage.

A few limits apply to what you can bundle: up to 500 files per build, and up to 5 MiB per file. node_modules, .git, .next, dist, and top-level dotfiles are ignored by default; add a .sprigrignore file (one glob or literal per line, # for comments) to ignore more.

Pulling a site’s source

Section titled “Pulling a site’s source”

sprigr pull recovers the source a site was deployed from and writes it back to a directory, so you can edit and redeploy even if the original files are gone.

Terminal window
sprigr pull <siteId> --dir ./recovered

By default it recovers the source behind the currently live deployment. Pass --build <buildId> to pull a specific build. The command refuses to write into a non-empty directory unless you pass --force, so a stray pull cannot overwrite a working tree. After writing, it prints the exact sprigr deploy command to redeploy the recovered tree.

Inspecting builds

Section titled “Inspecting builds”

List recent builds for a site:

Terminal window
sprigr builds list <siteId> --limit 20

Fetch a single build’s status, including its captured build log once the build has finished:

Terminal window
sprigr builds get <siteId> <buildId>

builds get prints the build as JSON followed by the build log, which is the first place to look when a build fails. Pass --no-log to print only the JSON, which is handy when scripting.

The app command

Section titled “The app command”

sprigr app is a separate set of subcommands for publishing and installing Sprigr marketplace apps (packaged, distributable integrations), not for deploying ordinary websites. It is aimed at app publishers and covers validating and publishing an app bundle, upgrading an install, and managing publisher secrets. Run sprigr app --help for the subcommand list. Most people never need it — for regular site deploys, use sprigr deploy.

Endpoints

Section titled “Endpoints”

By default the CLI talks to the production API. You rarely need to change this, but you can override the endpoint with --endpoint <url> or the SPRIGR_ENDPOINT environment variable, which also accepts the shortcuts staging and prod.

Next steps

Section titled “Next steps”