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

# link

> Link a local project to a Base44 project

Link a local project to Base44. You can create a new backend project or link to an existing Base44 project, including apps built in the Base44 online app editor, such as a clone of a repo created by the [GitHub integration](https://docs.base44.com/developers/app-code/local-development/github.md). The command writes the project ID to your [`.app.jsonc`](https://docs.base44.com/developers/backend/overview/project-structure#app-jsonc) file.

The `.app.jsonc` file is gitignored, so linking is per checkout. Every fresh clone needs `base44 link`, or the `--app-id` flag, before app-scoped commands like [`dev`](https://docs.base44.com/developers/references/cli/commands/dev) can run.

Use this when you have a local project but haven't yet connected it to Base44.

> [!NOTE]
>
> If you don't have any project files yet, use [`base44 create`](https://docs.base44.com/developers/references/cli/commands/create) to generate a new project. The `create` command generates new code, while `link` connects existing code files to a backend. For a complete guide, see [Link an Existing Backend Project](https://docs.base44.com/developers/backend/overview/link-existing-project.md).

## Requirements

* Must be run from a directory containing a `base44/config.jsonc` file.
* Project must not already be linked. If an [`.app.jsonc`](https://docs.base44.com/developers/backend/overview/project-structure#app-jsonc) file with an app ID already exists, the command will fail.

## Usage

```bash theme={null}
base44 link
```

An interactive prompt will guide you through creating a new project or selecting an existing one.

For a step-by-step guide on linking existing projects, see [Link an Existing Backend Project](https://docs.base44.com/developers/backend/overview/link-existing-project.md).

## Flags

| Flag | Description |
| - | - |
| `-c, --create` | Create a new backend project on Base44. This skips the selection prompt. |
| `-n, --name <name>` | Project name. Required when using `--create`. |
| `-d, --description <description>` | Project description. |
| `-w, --workspace <id>` | Workspace ID to create the app in when using `--create`. Defaults to your personal workspace. |
| `--app-id <id>` | Target the specified app, skipping the selection prompt. See [Select a target app](https://docs.base44.com/developers/references/cli/commands/introduction.md#select-a-target-app). |

## Non-interactive usage

For scripts or CI environments, use the flags to skip prompts:

Create a new project:

```bash theme={null}
base44 link --create --name "my-project" --description "My app"
```

Create a new project in a specific workspace:

```bash theme={null}
base44 link --create --name "my-project" --workspace 507f1f77bcf86cd799439011
```

Link to an existing project. You can find the app ID in the app's URL in the Base44 online app editor, `app.base44.com/apps/<id>/...`:

```bash theme={null}
base44 link --app-id "your-app-id"
```

## See also

* [`create`](https://docs.base44.com/developers/references/cli/commands/create): Create a new Base44 project
* [`scaffold`](https://docs.base44.com/developers/references/cli/commands/scaffold): Set up local project files for an existing Base44 app
* [`workspace list`](https://docs.base44.com/developers/references/cli/commands/workspace-list): List the workspaces you belong to
* [`dashboard open`](https://docs.base44.com/developers/references/cli/commands/dashboard-open): Open your app in the dashboard
* [`site open`](https://docs.base44.com/developers/references/cli/commands/site-open): Open the deployed site in your browser
* [Project Structure](https://docs.base44.com/developers/backend/overview/project-structure.md): How project files are organized


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