The Budgethost CLI uploads your project, builds it on Budgethost, waits for the deployment result, and prints its public URL when available. You do not need Docker on your computer for source deployments.
CLI version: 0.1.0. Requires PowerShell 7.4 or newer, including on macOS and Linux. Windows PowerShell 5.1 is a different program and cannot run this CLI.
Before you start#
Create and configure your service in Portal: set its container port,
readiness check, environment variables and persistent storage. Download a
service-scoped token's .env credentials and keep it outside your project.
This CLI deploys an existing service; it does not create services or configure
databases, storage or secrets for you.
Your source project needs a Dockerfile and .dockerignore at its root. An AI
assistant can prepare these for your app. The Dockerfile must produce a Linux
container that listens on the port configured in Portal.
Windows setup#
Install PowerShell 7 from a terminal:
winget install --id Microsoft.PowerShell --source winget
Open PowerShell 7 from the Start menu. Check that $PSVersionTable.PSVersion
reports 7.4 or newer, then download the installer:
Invoke-WebRequest `
https://documentation.api.budgethost.io/downloads/install-budgethost.ps1 `
-OutFile "$HOME\Downloads\install-budgethost.ps1"
Review the downloaded script, then run it:
Unblock-File "$HOME\Downloads\install-budgethost.ps1"
& "$HOME\Downloads\install-budgethost.ps1"
budgethost version
If Windows blocks local scripts, follow your organization's execution-policy
rules. On a personally managed computer, Set-ExecutionPolicy -Scope CurrentUser RemoteSigned permits local scripts and downloaded scripts you explicitly unblock.
Do not bypass an organization policy. See Microsoft's
PowerShell installation guide
for other installation options.
macOS setup#
Install PowerShell using Microsoft's macOS installation instructions. With Homebrew already installed, its PowerShell formula is another option:
brew install powershell
pwsh
You are now in PowerShell. Download, review and run the installer:
Invoke-WebRequest `
https://documentation.api.budgethost.io/downloads/install-budgethost.ps1 `
-OutFile "$HOME/install-budgethost.ps1"
# Review the file before running it.
& "$HOME/install-budgethost.ps1"
budgethost version
Linux setup#
Install PowerShell 7.4 or newer using Microsoft's instructions for your distribution. Then start it:
pwsh
In PowerShell, download, review and run the installer:
Invoke-WebRequest `
https://documentation.api.budgethost.io/downloads/install-budgethost.ps1 `
-OutFile "$HOME/install-budgethost.ps1"
# Review the file before running it.
& "$HOME/install-budgethost.ps1"
budgethost version
The installer puts the CLI in $HOME/.budgethost and adds a budgethost function
to your PowerShell profile. It is available in this session and future PowerShell
sessions. It does not add a Bash or zsh command. To run it from those shells:
pwsh -NoProfile -File "$HOME/.budgethost/budgethost.ps1" help
Link your project once#
In PowerShell, open your project folder. Windows example:
Set-Location "$HOME\Projects\my-app"
budgethost init -CredentialsFile "$HOME\Downloads\my-service.env"
On macOS or Linux, use your local paths, for example:
Set-Location "$HOME/projects/my-app"
budgethost init -CredentialsFile "$HOME/.service.env"
This creates budgethost.json with your service ID, API address and the path to
your credentials. The token itself stays in the downloaded file. Keep the
credentials private; on macOS/Linux, run chmod 600 on that file. The CLI parses
the two credential values as text and does not execute the .env file.
The local credentials path is machine-specific. Keep budgethost.json out of Git
or remove its credentials_file property before sharing it. In automation, use
init -ServiceId YOUR_SERVICE_ID and provide SERVICE_TOKEN through your CI secret
store. That environment variable takes precedence over the credentials file.
Deploy an update#
Review what will be uploaded before your first deployment and after adding files:
budgethost up -DryRun
Then deploy:
budgethost up
The CLI prints the deployment ID and stage changes, then the public URL after success. A nonzero exit code means the command failed or could not confirm success. The first public URL can take time to appear; HTTPS appears after the certificate is applied. Refresh the address later with:
budgethost url
Subsequent updates use the same budgethost up command. Configured persistent
storage stays attached; the CLI does not recreate it.
Control what gets uploaded#
Source uploads include current files, including uncommitted and untracked files.
Common local files are always excluded: Git metadata, node_modules, bin, obj,
.env files, common private-key and database files, credential JSON files, and
budgethost.json. The selected credentials file is also excluded.
Add project-specific exclusions to .budgethostignore, created by init:
# One pattern per line
uploads
backups
test-results
config/local.json
*.log
A pattern without / matches a name anywhere in the project. A pattern with /
matches from the project root. These are PowerShell wildcard patterns (*, ?,
[abc]), not Git/Docker ignore syntax; ! negation is rejected. Excluded folders
are not traversed. Links are rejected unless excluded.
.dockerignore controls the remote Docker build context; it does not filter the
archive uploaded to Budgethost. Keep secrets in Portal or the secret API. Filename
filters cannot recognize secrets embedded in ordinary source files, so review the
dry-run list and source contents. Build output can also reveal secrets if your
Dockerfile prints them.
Resume or inspect a deployment#
If connectivity fails or you close the terminal:
budgethost up -Resume
This uses the same saved archive, deployment ID and retry keys. Changes to local source are not included in a resumed release. Do not delete local state while recovering. The CLI prevents a fresh release when the previous one is unresolved. Ctrl+C and the waiting timeout stop the local command, not the remote deployment.
budgethost status
budgethost logs
budgethost status -DeploymentId YOUR_DEPLOYMENT_ID
budgethost up -Resume -TimeoutMinutes 60
Logs are deployment/build logs, not a live application output stream. A failed deployment exits nonzero and does not trigger automatic rollback. Use the explicit rollback API when appropriate; it restores an image, not database contents or files.
Local retry state is stored under your operating system's local application-data
directory, in Budgethost/deployments. Archives are removed after a confirmed
terminal result; interrupted releases retain their archive for recovery. State
contains a token fingerprint, never the token. Finish active deployments before
rotating tokens: retry keys belong to the original credential.
Deploy a prebuilt image#
If you prefer building locally, install Docker and build for the service's target
platform reported by the API capabilities. Save exactly one image with docker save:
# The image must already be built for the service's Linux target platform.
docker save --output "$HOME/my-app.tar" my-app:release
budgethost up -ImageArchive "$HOME/my-app.tar"
Use docker save, not docker export. No registry login or push is needed.
Direct API examples on each OS#
The deployment guide and slice guide include Bash, PowerShell and Node.js versions at every step. The CLI is optional; you can call the same public API directly using your preferred language.
Windows API prerequisites#
Use PowerShell 7.4+ for the PowerShell examples. They use Invoke-RestMethod,
PowerShell's JSON commands and .NET archive support. No WSL is required.
For Node.js examples, install Node.js 22 or newer.
The Node.js source-archive example also requires tar on PATH, as provided by
modern Windows. Docker is only needed for local image builds.
macOS API prerequisites#
Use Bash for the Bash examples. With Homebrew installed:
brew install curl jq python
export PATH="$(brew --prefix curl)/bin:$PATH"
bash
The examples work with macOS's tar and use Python for archive size and SHA-256,
so you do not need GNU coreutils or GNU tar. The source-packaging command disables
AppleDouble metadata. Keep the --format=ustar option.
You can also use Node.js 22+ or PowerShell 7.4+ on macOS. The Node.js examples use built-in modules without npm dependencies. Install Node.js from its official downloads.
Linux API prerequisites#
For Bash on Debian or Ubuntu:
sudo apt-get install bash curl jq tar python3
bash
Curl must support --fail-with-body (7.76+). Use your distribution's package
manager on other Linux distributions. Alternatively, use Node.js 22+ or
PowerShell 7.4+ with the corresponding examples.
Update or remove the CLI#
To update, download and run the installer again. It replaces the script, checks the published SHA-256, and leaves project configuration and deployment state intact. The checksum detects an incomplete or mismatched download; it is not a signing key.
To remove it, delete $HOME/.budgethost and remove the # Budgethost CLI function
line from your PowerShell profile ($PROFILE.CurrentUserAllHosts). Remove local
deployment state only when you no longer need to recover a release.