Project linking

Link a directory to an application, read the project.json the CLI writes, and decide whether to commit it.

A project link records which application the current directory belongs to, so deploy, env and deployments stop needing --app on every run. It is one small file at .gigadrive/project.json.

Linking a directory

gigadrive link

The CLI lists the applications you can reach, narrowed to --org when you pass one. A single application is selected without asking. Several open a picker titled Select an application to link, where each entry reads Marketing site (Gigadrive GmbH). Pass --app to skip the picker.

Linked this directory to application 0195c11c-0000-7000-8000-000000000042.
Tip: add ".gigadrive/" to your .gitignore.

Flag	Alias	Description
`--app`	`-a`	Application ID to link (skips the interactive picker)
`--org`	`-o`	Only list applications belonging to this organization ID

An account with no applications gets No applications found. Create one in the Gigadrive console, then run "gigadrive link" again. An --app that is not in your list gets Application "<id>" was not found among your applications.

That list is a single page of ten, the API default, and the CLI never asks for a second page. Once you own more than ten applications, pass --org so the one you want is on the page.

You do not have to link first. gigadrive deploy in an unlinked directory creates an application, writes the link, and then deploys.

The file

{
  "applicationId": "0195c11c-0000-7000-8000-000000000042",
  "organizationId": "0195c0aa-0000-7000-8000-0000000000ff"
}

applicationId is required. organizationId is optional, and the CLI writes it whenever it knows which organization owns the application. Nothing else is read from the file, and it holds no credential of any kind. Your token lives in ~/.gigadrive/auth.json, covered in Authentication.

Whether to commit it

The CLI's own advice, printed every time it links, is to add .gigadrive/ to .gitignore. It does not edit .gitignore for you, so that is a manual step.

Keep the link out of the repository when contributors deploy to their own applications, which is the common case for anyone testing a fork or a personal preview. Committing it is defensible when the whole team deploys the same repository to one application and you want gigadrive deploy to be identical on every machine. Pick one and be explicit about it, because a committed link quietly redirects a colleague's deploy.

Which commands read the link

Command	What it takes from the link
`deploy`	`applicationId`, when `--app` is absent
`deployments list`	`applicationId` as a filter, when `--app` is absent
`env list`, `env set`, `env rm`	`applicationId`, unless `--org` switches to organization scope
`env pull`	`applicationId`, when `--app` is absent
`setup`	`applicationId`, and an existing link makes `--app` and `--org` ignored
`ai usage`, `ai budgets`, `ai policies`	`organizationId`, when `--org` is absent

Most of these fail with This directory is not linked to an application. Run "gigadrive link" first. when the link is missing and no flag substitutes for it. Two behave differently. deployments list applies no application filter at all in an unlinked directory, so it lists deployments across everything you can see. The ai governance commands report No organization is linked. Pass --org <id> or re-run "gigadrive link". when the link exists but carries no organizationId.

A file that exists but is broken is an error, not the same as being unlinked. Invalid JSON reports .gigadrive/project.json contains invalid JSON, and a file whose shape does not match reports .gigadrive/project.json has an invalid schema.

Unlinking

gigadrive unlink

This deletes .gigadrive/project.json and prints Unlinked this directory. A missing file is treated as success. The command takes no arguments and no options. Run it before gigadrive setup when you want to point the directory at a different application.