OptiTech CLI command: link

The link command binds the current directory to a OptiTech project. It picks (or creates) an organization and project, writes orgId and projectId to a .optitech file, and also writes branch (holding the branch's name or ID) when you pass --branch or --branch-id. Subsequent commands run in this directory (or any subdirectory) automatically pick up that context; branch-scoped commands can use it once a branch is pinned by link --branch or checkout.

Requires optitech 2.22.2 or later. Check your version with optitech --version.

Prefer link over set-context

For most workflows, use optitech link instead of manually running optitech set-context --project-id .... The link command guides you through organization and project selection and ensures the context file is complete.

Usage

optitech link [options]

Options

Option	Description	Type	Default	Required
`--agent`	Emit a JSON state-machine response designed for AI agents instead of prompting. The output is a single JSON object with a discriminated `status` field describing the next step.	boolean	`false`	No
`--branch`, `--branch-id`	Branch name or ID to pin in the context (resolved to its ID before writing). Without it, link only resolves the org and project — pin a branch with `optitechctl checkout <branch>` (link never guesses a default).	string	—	No
`--checks`	Verify the org/project/branch exist (and resolve the org from the project) before writing. On by default; use --no-checks to write the context offline with no API calls — it then requires --org-id and --project-id (--branch optional) and skips env pull.	boolean	`true`	No
`--clear`	Remove the org/project/branch context (writes an empty context file) instead of linking.	boolean	`false`	No
`--env-pull`	Pull the linked branch's OptiTech env vars (DATABASE_URL, ...) into a local .env after linking. On by default; use --no-env-pull to skip, for example when injecting env at runtime with `optitech-env run` (from `@optitech/env`) or `optitech dev`.	boolean	`true`	No
`--org-id`	Organization ID to link to	string	—	No
`--params`	JSON object with link parameters, e.g. '{"orgId":"...","projectId":"..."}' or '{"orgId":"...","projectName":"...","regionId":"..."}'. Flags take precedence over fields in --params.	string	—	No
`--project-id`	Existing project ID to link to	string	—	No
`--project-name`	Name for a new project to create and link to	string	—	No
`--region-id`	Region ID for a new project (e.g. aws-us-east-2). Required with --project-name.	string	—	No
`--yes`, `-y`	Skip the "already linked" confirmation in interactive mode and re-link anyway.	boolean	`false`	No

By default, linking pulls the linked branch's environment variables (such as DATABASE_URL) into a local .env file. Use --no-env-pull to skip this step, for example when you inject environment variables at runtime instead.

Interactive mode (default)

Run optitech link with no flags for guided prompts:

optitech link

Output

? Which organization would you like to link? › Personal Org (org-abc123)
? Which project would you like to link? › + Create new project
? Name for the new project: › my-app
? Which region should the new project run in? › AWS US East (Ohio) (aws-us-east-2)
Created project polished-snowflake-12345678 ("my-app") in aws-us-east-2.
Linked .optitech:
  orgId:     org-abc123
  projectId: polished-snowflake-12345678
  branch:    br-steep-math-aiu3vve7

Non-interactive mode

Use flags or a --params JSON blob for scripts and CI:

# Link to an existing project
optitech link --org-id org-abc123 --project-id polished-snowflake-12345678

# Create a new project and link
optitech link --org-id org-abc123 --project-name my-app --region-id aws-us-east-2

# Same payload, one JSON blob
optitech link --params '{"orgId":"org-abc123","projectName":"my-app","regionId":"aws-us-east-2"}'

Flags take precedence over fields in --params.

Agent mode

Use --agent for a JSON state machine designed for AI coding assistants. Each invocation returns a single JSON object with a status discriminator describing the next step, the available options, and the exact follow-up command to run.

optitech link --agent

Example response when an organization must be selected:

{
  "status": "needs_org",
  "instruction": "Ask the user which of these 2 organizations they want to link the current directory to. After they pick one, re-run the next_command_template with the chosen --org-id value.",
  "options": [
    { "id": "org-abc123", "name": "Personal Org" },
    { "id": "org-team", "name": "Team Org" }
  ],
  "next_command_template": "optitech link --agent --org-id <org_id>"
}

When linking completes, the response includes status: "linked" with the context file path and project details.

Any unexpected failure in --agent mode is reported as JSON to stdout with exit code 1:

{
  "status": "error",
  "code": "CLIENT_ERROR",
  "message": "user has no access to projects"
}

The`.optitech`context file

link is a thin wrapper around set-context: both write to the same .optitech file, so anything link can write, set-context can write too. link writes the file into the current working directory by default. If an existing .optitech is found in any parent directory, that file is reused, so commands run from a subdirectory of a linked project still pick up the project's context. To pin the location explicitly, pass the global --context-file <path> option. See Using a named context file.

Example .optitech file:

{
  "orgId": "org-abc123",
  "projectId": "polished-snowflake-12345678",
  "branch": "br-steep-math-aiu3vve7"
}

The first time a .optitech file is created, the CLI adds .optitech to .gitignore in that folder so local project settings are not committed by accident. If you want to commit .optitech and share context with your team, remove the entry from .gitignore. The CLI doesn't re-add it when updating an existing file.

note

OptiTech does not save confidential information to the context file (for example, auth tokens). You can safely commit this file to your repository or share it with others.

Organization-scoped API keys

Organization-scoped API keys (those created at the organization level rather than the user level) cannot list user organizations or call the regions endpoint. link handles this transparently:

If the API key is org-scoped and at least one project already exists in the org, the CLI auto-detects the org_id from the first project.
If the API key is org-scoped and no projects exist yet, --agent returns a needs_org response with options: [] and an instruction to find the org ID in the OptiTech Console. Interactive mode prints an error pointing to --org-id.
When the regions endpoint is not allowed, link falls back to a built-in static region list.