---
title: 'flexkit link'
description: 'Link a folder to a Flexkit project so CLI commands run in it act on that project.'
---

# `flexkit link`

Links the current folder to a Flexkit project. Afterwards, every command you run in this folder (or in any folder below it) acts on that project, so you don't have to pass `--project` each time.

The link is saved in `.flexkit/project.json`. If the folder has a `.gitignore` file or is a git repository, `flexkit link` adds `.flexkit` to `.gitignore`: the link belongs to your machine, not to the repository.

## Synopsis

```bash
flexkit link [nameOrId] [--scope <team>] [--yes] [--json]
```

Without an argument, `flexkit link` lists the projects of your current team and asks you to pick one. With a project name or id, it links to that project directly, which is what scripts should use.

## Examples

```bash
# Pick a project from a list and link this folder to it
flexkit link

# Link to a project by name or id
flexkit link my-shop
flexkit link abcdefghij

# Pick from the projects of another team
flexkit link --scope acme

# Replace an existing link without a prompt (useful in scripts)
flexkit link my-shop-staging --yes

# Print the saved link as JSON
flexkit link my-shop --json
```

## Options

| Option                  | Description                                                    |
| ----------------------- | -------------------------------------------------------------- |
| `-S`, `--scope <team>`  | Team to pick the project from. Defaults to your current team.  |
| `-y`, `--yes`           | Replace an existing link without asking.                       |
| `--json`                | Print the saved link (project, team and file path) as JSON.    |

You can also use all [global options](/docs/cli/global-options).

## How commands choose a project

Commands that act on a project resolve it in this order:

1. The `--project <id>` (`-p`) option.
2. The `FLEXKIT_PROJECT_ID` environment variable.
3. The nearest `.flexkit/project.json`, searched from the current folder upwards.
4. The project in the local `flexkit.config.ts`, when it defines exactly one.

So a linked folder still lets you target another project for a single command:

```bash
flexkit automations ls --project abcdefghij
```

## The `.flexkit/project.json` file

```json
{
  "projectId": "abcdefghij",
  "projectName": "my-shop",
  "teamId": "team_123",
  "teamName": "Acme"
}
```

Don't commit this file. Every developer links their own checkout, which lets them point it at a development project. In CI, set `FLEXKIT_PROJECT_ID` instead of committing a link.

## Related

- [`flexkit unlink`](/docs/cli/unlink) removes the link.
- [`flexkit project`](/docs/cli/project) lists, creates and removes projects.


---

[View full sitemap](/docs/sitemap.md)