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

# CLI Commands Overview

> Complete reference for all Base44 CLI commands

> [!NOTE]
>
> The backend service and CLI are currently in beta. We're actively improving the platform and documentation based on user feedback. Share your thoughts and feature requests on our [GitHub Discussions page](https://github.com/orgs/base44/discussions).

The Base44 CLI provides commands for authentication, project management, and syncing resources with your Base44 backend.

## Command overview

| Command | Description |
| - | - |
| [`actors delete`](https://docs.base44.com/developers/references/cli/commands/actors-delete) | Delete one or more deployed actors. |
| [`actors deploy`](https://docs.base44.com/developers/references/cli/commands/actors-deploy) | Deploy local actors to Base44. |
| [`agent-skills pull`](https://docs.base44.com/developers/references/cli/commands/agent-skills-pull) | Pull agent skills from Base44 to local files. |
| [`agent-skills push`](https://docs.base44.com/developers/references/cli/commands/agent-skills-push) | Push local agent skills to Base44. |
| [`agents pull`](https://docs.base44.com/developers/references/cli/commands/agents-pull) | Pull agent configurations from Base44 to local files. |
| [`agents push`](https://docs.base44.com/developers/references/cli/commands/agents-push) | Push local agent configurations to Base44. |
| [`api catalog`](https://docs.base44.com/developers/references/cli/commands/api-catalog) | List the Base44 API's areas, or every operation in one area. |
| [`api fetch`](https://docs.base44.com/developers/references/cli/commands/api-fetch) | Call any Base44 API operation. |
| [`api grep`](https://docs.base44.com/developers/references/cli/commands/api-grep) | Search the Base44 API spec with a regular expression. |
| [`api search`](https://docs.base44.com/developers/references/cli/commands/api-search) | Search Base44 API operations by keyword. |
| [`auth password-login`](https://docs.base44.com/developers/references/cli/commands/auth-password-login) | Enable or disable username and password login in local config. |
| [`auth pull`](https://docs.base44.com/developers/references/cli/commands/auth-pull) | Pull auth config from Base44 to your local project. |
| [`auth push`](https://docs.base44.com/developers/references/cli/commands/auth-push) | Push local auth config to Base44. |
| [`auth social-login`](https://docs.base44.com/developers/references/cli/commands/auth-social-login) | Enable or disable social login providers in local config. |
| [`auth sso`](https://docs.base44.com/developers/references/cli/commands/auth-sso) | Configure SSO identity providers in local config. |
| [`branches list`](https://docs.base44.com/developers/references/cli/commands/branches-list) | List the branch names you can target with `--branch`. |
| [`build`](https://docs.base44.com/developers/references/cli/commands/build) | Build the site with the Base44 app ID injected. |
| [`connectors initiate`](https://docs.base44.com/developers/references/cli/commands/connectors-initiate) | Set up a single connector and start its OAuth flow. |
| [`connectors list-available`](https://docs.base44.com/developers/references/cli/commands/connectors-list-available) | List all available integration types. |
| [`connectors pull`](https://docs.base44.com/developers/references/cli/commands/connectors-pull) | Pull connector configurations from Base44 to local files. |
| [`connectors push`](https://docs.base44.com/developers/references/cli/commands/connectors-push) | Push local connector configurations to Base44. |
| [`create`](https://docs.base44.com/developers/references/cli/commands/create) | Create a new Base44 project from a template. |
| [`dashboard open`](https://docs.base44.com/developers/references/cli/commands/dashboard-open) | Open the app dashboard in your browser. |
| [`deploy`](https://docs.base44.com/developers/references/cli/commands/deploy) | Deploy all project resources to Base44. |
| [`dev`](https://docs.base44.com/developers/references/cli/commands/dev) | Start a local development server. |
| [`eject`](https://docs.base44.com/developers/references/cli/commands/eject) | Clone an existing Base44 app into a separate local project. |
| [`entities push`](https://docs.base44.com/developers/references/cli/commands/entities-push) | Push local entity schemas to Base44. |
| [`exec`](https://docs.base44.com/developers/references/cli/commands/exec) | Run a script with the Base44 SDK pre-authenticated. |
| [`functions delete`](https://docs.base44.com/developers/references/cli/commands/functions-delete) | Delete one or more deployed backend functions. |
| [`functions deploy`](https://docs.base44.com/developers/references/cli/commands/functions-deploy) | Deploy local functions to Base44. |
| [`functions list`](https://docs.base44.com/developers/references/cli/commands/functions-list) | List all deployed backend functions. |
| [`functions pull`](https://docs.base44.com/developers/references/cli/commands/functions-pull) | Download deployed functions to your local project. |
| [`link`](https://docs.base44.com/developers/references/cli/commands/link) | Link a local project to a backend project on Base44. |
| [`login`](https://docs.base44.com/developers/references/cli/commands/login) | Authenticate with Base44. |
| [`logout`](https://docs.base44.com/developers/references/cli/commands/logout) | Sign out and clear stored credentials. |
| [`logs`](https://docs.base44.com/developers/references/cli/commands/logs) | View function logs. |
| [`sandbox checkpoint`](https://docs.base44.com/developers/references/cli/commands/sandbox-checkpoint) | Create a restore-point checkpoint of an app's remote sandbox. |
| [`sandbox edit`](https://docs.base44.com/developers/references/cli/commands/sandbox-edit) | Apply exact string replacements to a file in the sandbox. |
| [`sandbox grep`](https://docs.base44.com/developers/references/cli/commands/sandbox-grep) | Search files for a pattern in an app's remote sandbox. |
| [`sandbox ls`](https://docs.base44.com/developers/references/cli/commands/sandbox-ls) | List directory entries in an app's remote sandbox. |
| [`sandbox read`](https://docs.base44.com/developers/references/cli/commands/sandbox-read) | Read file contents from an app's remote sandbox. |
| [`sandbox run`](https://docs.base44.com/developers/references/cli/commands/sandbox-run) | Run a shell command in an app's remote sandbox. |
| [`sandbox write`](https://docs.base44.com/developers/references/cli/commands/sandbox-write) | Create or overwrite a file in an app's remote sandbox. |
| [`scaffold`](https://docs.base44.com/developers/references/cli/commands/scaffold) | Set up local project files for an existing Base44 app. |
| [`secrets delete`](https://docs.base44.com/developers/references/cli/commands/secrets-delete) | Delete one or more project secrets. |
| [`secrets list`](https://docs.base44.com/developers/references/cli/commands/secrets-list) | List project secrets. |
| [`secrets set`](https://docs.base44.com/developers/references/cli/commands/secrets-set) | Set one or more project secrets. |
| [`site deploy`](https://docs.base44.com/developers/references/cli/commands/site-deploy) | Deploy built site files to Base44 hosting. |
| [`site open`](https://docs.base44.com/developers/references/cli/commands/site-open) | Open the deployed site in your browser. |
| [`types generate`](https://docs.base44.com/developers/references/cli/commands/types-generate) | Generate TypeScript types from project resources. |
| [`visibility`](https://docs.base44.com/developers/references/cli/commands/visibility) | Set the app's visibility level. |
| [`whoami`](https://docs.base44.com/developers/references/cli/commands/whoami) | Display the current authenticated user. |
| [`workflows list`](https://docs.base44.com/developers/references/cli/commands/workflows-list) | List this app's workflows. |
| [`workflows runs`](https://docs.base44.com/developers/references/cli/commands/workflows-runs) | List workflow runs for this app. |
| [`workspace get`](https://docs.base44.com/developers/references/cli/commands/workspace-get) | Show details for a single workspace by ID. |
| [`workspace list`](https://docs.base44.com/developers/references/cli/commands/workspace-list) | List the workspaces you belong to. |
| [`workspace move`](https://docs.base44.com/developers/references/cli/commands/workspace-move) | Move an app to another workspace. |

## Command syntax

All Base44 CLI commands follow this general syntax:

```bash theme={null}
base44 <command> [subcommand] [flags]
```

Where:

* `<command>` is the primary action (for example, `login`, `create`, `entities`)
* `[subcommand]` is an optional secondary action (for example, `entities push`)
* `[flags]` are optional parameters that modify the command's behavior

Some flags are listed with both a short and a long form, like `-n, --limit <n>`. These are the same flag, not two different ones. Use whichever form you prefer.

## Global flags

The following flags are available for all commands:

| Flag | Description |
| - | - |
| `--help` | Display help information for any command. |
| `--version` | Display the CLI version. |
| `--app-id <id>` | [Target a specific app](#select-a-target-app). |
| `--branch <name>` | [Target a branch of the app](#target-a-branch). Sandbox commands only. |
| `--json` | [Output the result as JSON](#json-output). |

## Select a target app

When you work on a project locally, the CLI reads the target app from `base44/.app.jsonc` automatically. For day-to-day work, you don't need to do anything.

You can also target a different app explicitly when running commands that don't need a local project, like [`logs`](https://docs.base44.com/developers/references/cli/commands/logs) and [`exec`](https://docs.base44.com/developers/references/cli/commands/exec). For example, tail logs from a production app, or run a script against an app you built in the Base44 online app editor.

The [`sandbox`](https://docs.base44.com/developers/app-code/sandbox/overview) commands are always in this group. They read and write files in the app's cloud environment rather than on your machine, so they never use a local project at all.

Commands that need a local project, like [`deploy`](https://docs.base44.com/developers/references/cli/commands/deploy) and [`entities push`](https://docs.base44.com/developers/references/cli/commands/entities-push), only work from inside one and always use the linked project's app.

You can specify the target app in three ways, in order of priority:

| Source | Description |
| - | - |
| `--app-id <id>` flag | Target a specific app. When set, the CLI ignores the project in the current directory and uses the project with this app id instead. |
| `BASE44_APP_ID` env variable | Same effect as the `--app-id` flag. Useful for CI, AI agents, and one-off shell sessions. |
| `base44/.app.jsonc` | The linked app of the local project, used when neither the `--app-id` flag nor the `BASE44_APP_ID` environment variable is set. |

## Target a branch

The [`sandbox`](https://docs.base44.com/developers/app-code/sandbox/overview) commands work on the app's `main` branch by default. To read or edit files on another branch instead, pass `--branch <name>` with the branch's exact name. Names are case-sensitive, and the flag goes anywhere on the command line:

```bash theme={null}
base44 sandbox read src/App.jsx --app-id <appId> --branch feature/checkout
```

Run [`branches list`](https://docs.base44.com/developers/references/cli/commands/branches-list) to see the names you can use. Only active branches are available. A name that doesn't match an active branch fails the command before anything is read or written, and so does a name that more than one active branch shares.

Commands outside the `sandbox` group don't accept the `--branch` flag.

## Environment variables

The CLI reads these environment variables:

| Variable | Description |
| - | - |
| `BASE44_ACCESS_TOKEN` | Authenticate with an access token, together with `BASE44_REFRESH_TOKEN`. See [Authenticate without a browser](#authenticate-without-a-browser). |
| `BASE44_API_KEY` | Authenticate with a workspace API key instead of `base44 login`. See [Authenticate without a browser](#authenticate-without-a-browser). |
| `BASE44_APP_ID` | Target a specific app, the same effect as the `--app-id` flag. See [Select a target app](#select-a-target-app). |
| `BASE44_DISABLE_TELEMETRY` | Set to `1` to turn off CLI telemetry and error reporting. |
| `BASE44_REFRESH_TOKEN` | The refresh token that goes with `BASE44_ACCESS_TOKEN`. |

## JSON output

Some commands, such as `workspace list`, `connectors list-available`, and `logs`, print plain text by default. Pass `--json` to return the result as JSON instead. This is useful when working with AI agents or scripts that need to parse the output.

With `--json`, stdout is a single JSON document. Status messages and logs go to stderr, so a script can read stdout without having to strip them out.

The `sandbox` commands and `api catalog`, `api grep`, and `api search` are the exception. They always return JSON, with or without `--json`. The flag still matters there, though, since it's what keeps the interactive status line out of stdout. The [`api fetch`](https://docs.base44.com/developers/references/cli/commands/api-fetch) command prints the server's response as it was sent.

```bash theme={null}
base44 logs --app-id <appId> --json
```

## Authentication requirements

Most commands require authentication, and you need a Base44 account to authenticate. Use [`base44 login`](https://docs.base44.com/developers/references/cli/commands/login) to authenticate before running commands like `create` or `entities push`. In an interactive terminal, these commands also start the login for you if you aren't logged in.

Commands that don't require authentication:

* `api catalog`, `api grep`, and `api search`
* `login`
* `logout`
* `types generate`

### Authenticate without a browser

The `base44 login` command needs a browser to approve the login. In CI pipelines, scripts, and AI agent environments, authenticate with an environment variable instead. Commands then run without a login. You can use either of these:

* **Workspace API key:** Set `BASE44_API_KEY` to a workspace API key, which starts with `b44k_`. Workspace owners and admins create keys on the [Secrets](https://docs.base44.com/Enterprise/workspace-secrets.md) page of the workspace settings.
* **Stripe Projects tokens:** Apps provisioned through Stripe Projects set `BASE44_ACCESS_TOKEN` and `BASE44_REFRESH_TOKEN` for you. Stripe Projects adds a `BASE44_PROJECTS_` prefix to the names, and the CLI reads the prefixed names too.

```bash theme={null}
export BASE44_API_KEY=b44k_your_key
base44 whoami
```

Run [`base44 whoami`](https://docs.base44.com/developers/references/cli/commands/whoami) to check which credentials the CLI is using.

> [!WARNING]
>
> **Workspace API key requirements:**
>
> * **Plan:** Business or Enterprise.
> * **Role:** Workspace owner or admin, to create the key.

> [!WARNING]
>
> Treat these values like passwords. Store them in your CI provider's secret storage and never commit them to source control.

## See also

* [CLI Overview](https://docs.base44.com/developers/references/cli/get-started/overview.md): Introduction to the Base44 CLI
* [Quickstart - Backend only](https://docs.base44.com/developers/backend/quickstart/templates/quickstart-backend-only.md): Create your first backend-only project
* [Quickstart - React](https://docs.base44.com/developers/backend/quickstart/templates/quickstart-react-template.md): Build a full-stack React app
* [Start from an existing Base44 app](https://docs.base44.com/developers/backend/overview/start-from-existing-app.md): Clone an existing project


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.