feat: pin a project and environment to a directory with vf link (COR-14197)

README.md

@@ -23,6 +23,7 @@ Realtime: Realtime gateway API service
   * [CLI Example Usage](#cli-example-usage)
   * [Authentication](#authentication)
   * [Browser sign-in (OAuth2)](#browser-sign-in-oauth2)
+  * [Link a project to a directory](#link-a-project-to-a-directory)
   * [Available Commands](#available-commands)
   * [Request Body Input](#request-body-input)
   * [Server Selection](#server-selection)
@@ -283,6 +284,32 @@ set, the CLI registers itself as a public client through the authorization
 server's dynamic client registration endpoint and caches the resulting
 `client_id` for later logins.
 
+## Link a project to a directory
+
+Every project command takes `--project-id` and `--environment-alias`. Link a
+directory once and leave them out:
+
+```bash
+vf link 6a67842584dac97c7626ebaa                          # environment "main"
+vf link 6a67842584dac97c7626ebaa --environment-alias dev
+```
+
+`vf link` checks that the project and environment exist, then writes
+`.voiceflow/project.json`: ids, the project name and the environment alias,
+nothing secret. Commands run in that directory, or in any directory below it,
+use the link. A linked value is only a fallback: an explicit flag, or a value in
+`--body` or stdin, always wins. `vf whoami` shows the link in
+effect, and `vf unlink` removes it.
+
+- **Deletes always name their target.** A link never fills in the project,
+  environment or workspace that `project delete`, `environment delete` or
+  `workspace delete` would destroy.
+- **The project id is in Creator**, under the agent's Settings → General
+  (Metadata). A Creator page URL will not do: the id in it is a version id.
+- **For coding agents**, `vf link` also prints a short snippet for the agent's
+  instructions file (`CLAUDE.md`, `AGENTS.md`), so the agent knows the project
+  is linked before it runs its first command.
+
 <!-- Start Available Commands [operations] -->
 ## Available Commands
 

docs/vf.md

@@ -43,12 +43,14 @@ vf [flags]
 * [vf explore](vf_explore.md)	 - Interactively browse and run commands
 * [vf function](vf_function.md)	 - Operations for function
 * [vf knowledge-base](vf_knowledge-base.md)	 - Operations for knowledge-base
+* [vf link](vf_link.md)	 - Pin a project and environment to this directory
 * [vf mcp-server](vf_mcp-server.md)	 - Operations for mcp-server
 * [vf mcp-tool](vf_mcp-tool.md)	 - Operations for mcp-tool
 * [vf playbook](vf_playbook.md)	 - Operations for playbook
 * [vf project](vf_project.md)	 - Operations for project
 * [vf tool](vf_tool.md)	 - Operations for tool
 * [vf transcript](vf_transcript.md)	 - Operations for transcript
+* [vf unlink](vf_unlink.md)	 - Remove the project link that applies to this directory
 * [vf variable](vf_variable.md)	 - Operations for variable
 * [vf version](vf_version.md)	 - Print the CLI version
 * [vf whoami](vf_whoami.md)	 - Display current authentication configuration

docs/vf_link.md

@@ -0,0 +1,59 @@
+## vf link
+
+Pin a project and environment to this directory
+
+### Synopsis
+
+Pin a Voiceflow project and environment to the current directory.
+
+Every vf command run here, or in any directory below, then uses them by
+default, so --project-id and --environment-alias can be left out. A linked
+value is only a fallback: an explicit flag, or a value in --body or stdin,
+always wins. Deleting a project, environment or workspace always needs its
+flag: a link never fills in what a delete destroys.
+
+The link is .voiceflow/project.json. It holds ids, the project name and the
+environment alias — nothing secret. Remove it with 'vf unlink'.
+
+The project id is in Creator under the agent's Settings → General (Metadata).
+A Creator page URL will not do: the id in it is a version id.
+
+```
+vf link <project-id> [flags]
+```
+
+### Examples
+
+```
+  vf link 6a67842584dac97c7626ebaa
+  vf link 6a67842584dac97c7626ebaa --environment-alias dev
+```
+
+### Options
+
+```
+  -e, --environment-alias string   Environment to link (default "main")
+  -h, --help                       help for link
+```
+
+### Options inherited from parent commands
+
+```
+      --agent-mode             Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
+      --color string           Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
+  -d, --debug                  Log request and response diagnostics to stderr
+      --dry-run                Preview the request that would be sent without executing it (output to stderr)
+  -H, --header stringArray     Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
+      --include-headers        Include HTTP response headers in the output
+  -q, --jq string              Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
+      --no-interactive         Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
+  -o, --output-format string   Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
+      --server-url string      Override the default server URL
+      --timeout string         HTTP request timeout (e.g., 30s, 5m, 100ms)
+      --token string           Voiceflow bearer token
+      --usage                  Print the CLI Usage schema in KDL format
+```
+
+### SEE ALSO
+
+* [vf](vf.md)	 - Realtime: Realtime gateway API service

docs/vf_unlink.md

@@ -0,0 +1,41 @@
+## vf unlink
+
+Remove the project link that applies to this directory
+
+### Synopsis
+
+Remove the .voiceflow/project.json that applies to the current directory —
+the one here, or the nearest one above. Commands then need --project-id and
+--environment-alias again.
+
+```
+vf unlink [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for unlink
+```
+
+### Options inherited from parent commands
+
+```
+      --agent-mode             Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
+      --color string           Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
+  -d, --debug                  Log request and response diagnostics to stderr
+      --dry-run                Preview the request that would be sent without executing it (output to stderr)
+  -H, --header stringArray     Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
+      --include-headers        Include HTTP response headers in the output
+  -q, --jq string              Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
+      --no-interactive         Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
+  -o, --output-format string   Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
+      --server-url string      Override the default server URL
+      --timeout string         HTTP request timeout (e.g., 30s, 5m, 100ms)
+      --token string           Voiceflow bearer token
+      --usage                  Print the CLI Usage schema in KDL format
+```
+
+### SEE ALSO
+
+* [vf](vf.md)	 - Realtime: Realtime gateway API service