diff --git a/.changeset/cli-targets.md b/.changeset/cli-targets.md
new file mode 100644
index 00000000..a2224ee8
--- /dev/null
+++ b/.changeset/cli-targets.md
@@ -0,0 +1,11 @@
+---
+'@powersync/cli-schemas': minor
+'@powersync/cli-core': minor
+'powersync': minor
+---
+
+Added named targets to `cli.yaml`. Link several Cloud instances from one project directory with `powersync link cloud --target=<name> --instance-id=<id>`, then pick one per command with `--target=<name>` or the `POWERSYNC_TARGET` variable. The top-level `instance_id`, `org_id` and `project_id` fields remain the default target.
+
+- `powersync fetch instances` lists the targets of each linked directory.
+- Commands that work with both Cloud and self-hosted instances now let `--instance-id` or `--api-url` decide the context, even when `cli.yaml` is linked to the other type.
+- When a linked directory has no `service.yaml`, the error now suggests `powersync pull instance`.
diff --git a/.gitignore b/.gitignore
index 502a4c85..2ea100fc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -150,3 +150,4 @@ playground/
 
 # IDE
 .idea
+
diff --git a/cli/README.md b/cli/README.md
index 17de9234..2bc32285 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -154,7 +154,19 @@ export INSTANCE_ID=<instance-id>
 powersync generate schema --output-path=schema.ts --output=ts
 ```
 
-**Tip:** To avoid passing `--instance-id` on every command, run **`powersync link cloud --instance-id=<id>`** once. The CLI writes `cli.yaml` in the current directory, and subsequent commands use that instance without flags or env vars.
+**Tip:** To avoid passing `--instance-id` on every command, run **`powersync link cloud --instance-id=<id>`** once. The CLI writes `cli.yaml` in the current directory, and subsequent commands use that instance without flags or env vars. To work with several instances from one directory, see the next section.
+
+## Several instances from one directory
+
+Link each instance as a named target, then pick one per command:
+
+```sh
+powersync link cloud --target=staging --instance-id=<id>
+powersync deploy --target=staging
+POWERSYNC_TARGET=staging powersync deploy sync-config # for scripts and CI
+```
+
+Commands without a target use the top-level link in `cli.yaml`. See [docs/usage.md](../docs/usage.md#configuring-multiple-instances-eg-dev-staging-production) for the full walkthrough.
 
 # Self-hosted
 
@@ -253,6 +265,7 @@ You can supply instance and auth context via environment variables (useful for C
 
 - **`PS_ADMIN_TOKEN`** — PowerSync personal access token for Cloud commands. [Learn more](https://docs.powersync.com/usage/tools/cli#personal-access-token).
 - **`INSTANCE_ID`** — Instance ID (Cloud). Get IDs from the [PowerSync Dashboard](https://dashboard.powersync.com) or **`powersync fetch instances`**.
+- **`POWERSYNC_TARGET`** — Name of a target defined in `cli.yaml` (Cloud). Same as passing `--target`.
 - **`API_URL`** — Self-hosted PowerSync API base URL (e.g. `https://powersync.example.com`).
 
 Example (Cloud):
@@ -261,7 +274,7 @@ Example (Cloud):
 PS_ADMIN_TOKEN=your-token INSTANCE_ID=123 powersync status
 ```
 
-See [docs/usage.md](../docs/usage.md) for full usage and resolution order (flags, env, cli.yaml).
+See [docs/usage.md](../docs/usage.md) for full usage and resolution order (flags, cli.yaml, env).
 
 # Commands
 
@@ -374,7 +387,7 @@ _See code: [@oclif/plugin-commands](https://github.com/oclif/plugin-commands/blo
 
 ```
 USAGE
-  $ powersync compact [--directory <value>] [--instance-id <value>] [--timeout <value>]
+  $ powersync compact [--directory <value>] [--target <value> | --instance-id <value>] [--timeout <value>]
 
 FLAGS
   --timeout=<value>  [default: 30] Maximum time to wait for compaction to complete, in minutes. Use 0 to wait
@@ -387,6 +400,7 @@ PROJECT FLAGS
 
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  PowerSync Cloud instance ID. Manually passed if the current context has not been linked.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   [Cloud only] Compact the linked Cloud instance.
@@ -429,8 +443,8 @@ _See code: [src/commands/configure/ide.ts](https://github.com/powersync-ja/power
 
 ```
 USAGE
-  $ powersync deploy [--deploy-timeout <value>] [--dry-run] [--directory <value>] [--instance-id <value>]
-    [--sync-config-file-path <value>] [--skip-validations <value> | --validate-only <value>]
+  $ powersync deploy [--deploy-timeout <value>] [--dry-run] [--directory <value>] [--target <value> |
+    --instance-id <value>] [--sync-config-file-path <value>] [--skip-validations <value> | --validate-only <value>]
 
 FLAGS
   --deploy-timeout=<value>    [default: 300] Seconds to wait after scheduling a deploy before timing out while polling
@@ -451,6 +465,7 @@ PROJECT FLAGS
 
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  PowerSync Cloud instance ID. Manually passed if the current context has not been linked.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   [Cloud only] Deploy local config to the linked Cloud instance (connections + auth + sync config).
@@ -477,8 +492,8 @@ _See code: [src/commands/deploy/index.ts](https://github.com/powersync-ja/powers
 
 ```
 USAGE
-  $ powersync deploy service-config [--deploy-timeout <value>] [--dry-run] [--directory <value>] [--instance-id <value>]
-    [--skip-validations <value> | --validate-only <value>]
+  $ powersync deploy service-config [--deploy-timeout <value>] [--dry-run] [--directory <value>] [--target <value> |
+    --instance-id <value>] [--skip-validations <value> | --validate-only <value>]
 
 FLAGS
   --deploy-timeout=<value>    [default: 300] Seconds to wait after scheduling a deploy before timing out while polling
@@ -497,6 +512,7 @@ PROJECT FLAGS
 
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  PowerSync Cloud instance ID. Manually passed if the current context has not been linked.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   [Cloud only] Deploy only local service config to the linked Cloud instance.
@@ -520,8 +536,8 @@ _See code: [src/commands/deploy/service-config.ts](https://github.com/powersync-
 
 ```
 USAGE
-  $ powersync deploy sync-config [--deploy-timeout <value>] [--dry-run] [--directory <value>] [--instance-id <value>]
-    [--sync-config-file-path <value>] [--skip-validations <value> | ]
+  $ powersync deploy sync-config [--deploy-timeout <value>] [--dry-run] [--directory <value>] [--target <value> |
+    --instance-id <value>] [--sync-config-file-path <value>] [--skip-validations <value> | ]
 
 FLAGS
   --deploy-timeout=<value>    [default: 300] Seconds to wait after scheduling a deploy before timing out while polling
@@ -540,6 +556,7 @@ PROJECT FLAGS
 
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  PowerSync Cloud instance ID. Manually passed if the current context has not been linked.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   [Cloud only] Deploy only local sync config to the linked Cloud instance.
@@ -563,7 +580,7 @@ _See code: [src/commands/deploy/sync-config.ts](https://github.com/powersync-ja/
 
 ```
 USAGE
-  $ powersync destroy [--directory <value>] [--instance-id <value>] [--confirm yes]
+  $ powersync destroy [--directory <value>] [--target <value> | --instance-id <value>] [--confirm yes]
 
 FLAGS
   --confirm=<option>  Set to "yes" to confirm destruction of the instance.
@@ -576,6 +593,7 @@ PROJECT FLAGS
 
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  PowerSync Cloud instance ID. Manually passed if the current context has not been linked.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   [Cloud only] Permanently destroy the linked Cloud instance.
@@ -733,8 +751,8 @@ Open the PowerSync configuration editor (Nitro server).
 
 ```
 USAGE
-  $ powersync edit config [--api-url <value> | --instance-id <value> |  | ] [--directory <value>] [--host
-    <value>] [--port <value>]
+  $ powersync edit config [--target <value> | [--api-url <value> | --instance-id <value> |  | ] | ] [--directory
+    <value>] [--host <value>] [--port <value>]
 
 FLAGS
   --host=<value>  [default: 127.0.0.1] Host to bind the editor preview server. Pass 0.0.0.0 to expose on all interfaces.
@@ -752,6 +770,7 @@ PROJECT FLAGS
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  [Cloud] PowerSync Cloud instance ID (BSON ObjectID). When set, context is treated as cloud
                          (exclusive with --api-url). Resolved: flag → cli.yaml → INSTANCE_ID.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   Open the PowerSync configuration editor (Nitro server).
@@ -772,7 +791,7 @@ _See code: [@powersync/cli-plugin-config-edit](https://github.com/powersync-ja/p
 
 ```
 USAGE
-  $ powersync fetch config [--directory <value>] [--instance-id <value>] [--output json|yaml]
+  $ powersync fetch config [--directory <value>] [--target <value> | --instance-id <value>] [--output json|yaml]
 
 FLAGS
   --output=<option>  [default: yaml] Output format: yaml or json.
@@ -785,6 +804,7 @@ PROJECT FLAGS
 
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  PowerSync Cloud instance ID. Manually passed if the current context has not been linked.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   [Cloud only] Print linked Cloud instance config (YAML or JSON).
@@ -833,8 +853,8 @@ Show instance diagnostics (connections, sync config, replication).
 
 ```
 USAGE
-  $ powersync fetch status [--api-url <value> | --instance-id <value> |  | ] [--directory <value>] [--output
-    human|json|yaml]
+  $ powersync fetch status [--target <value> | [--api-url <value> | --instance-id <value> |  | ] | ] [--directory
+    <value>] [--output human|json|yaml]
 
 FLAGS
   --output=<option>  [default: human] Output format: human-readable, json, or yaml.
@@ -852,6 +872,7 @@ PROJECT FLAGS
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  [Cloud] PowerSync Cloud instance ID (BSON ObjectID). When set, context is treated as cloud
                          (exclusive with --api-url). Resolved: flag → cli.yaml → INSTANCE_ID.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   Show instance diagnostics (connections, sync config, replication).
@@ -876,7 +897,8 @@ Generate client schema file from instance schema and sync config.
 ```
 USAGE
   $ powersync generate schema --output dart|dotNet|dotNetClass|js|jsLegacy|kotlin|swift|ts --output-path <value>
-    [--api-url <value> | --instance-id <value> |  | ] [--directory <value>] [--sync-config-file-path <value>]
+    [--target <value> | [--api-url <value> | --instance-id <value> |  | ] | ] [--directory <value>]
+    [--sync-config-file-path <value>]
 
 FLAGS
   --output=<option>      (required) [default: type] Output type: dart, dotNet, dotNetClass, js, jsLegacy, kotlin, swift,
@@ -898,6 +920,7 @@ PROJECT FLAGS
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  [Cloud] PowerSync Cloud instance ID (BSON ObjectID). When set, context is treated as cloud
                          (exclusive with --api-url). Resolved: flag → cli.yaml → INSTANCE_ID.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   Generate client schema file from instance schema and sync config.
@@ -919,8 +942,8 @@ Generate a development JWT for client connections.
 
 ```
 USAGE
-  $ powersync generate token --subject <value> [--api-url <value> | --instance-id <value> |  | ] [--directory
-    <value>] [--expires-in-seconds <value>] [--kid <value>]
+  $ powersync generate token --subject <value> [--target <value> | [--api-url <value> | --instance-id <value> |  | ]
+    | ] [--directory <value>] [--expires-in-seconds <value>] [--kid <value>]
 
 FLAGS
   --expires-in-seconds=<value>  [default: 43200] Expiration time in seconds. Default is 43,200 (12 hours).
@@ -940,6 +963,7 @@ PROJECT FLAGS
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  [Cloud] PowerSync Cloud instance ID (BSON ObjectID). When set, context is treated as cloud
                          (exclusive with --api-url). Resolved: flag → cli.yaml → INSTANCE_ID.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   Generate a development JWT for client connections.
@@ -1036,14 +1060,16 @@ _See code: [src/commands/init/self-hosted.ts](https://github.com/powersync-ja/po
 ```
 USAGE
   $ powersync link cloud [--directory <value>] [--instance-id <value>] [--org-id <value>] [--project-id <value>]
-    [--create]
+    [--target <value>] [--create]
 
 FLAGS
   --create               Create a new Cloud instance in the given org and project, then link. Do not supply
                          --instance-id when using --create.
-  --instance-id=<value>  PowerSync Cloud instance ID. Omit when using --create. Resolved: flag → INSTANCE_ID → cli.yaml.
+  --instance-id=<value>  PowerSync Cloud instance ID. Omit when using --create. Resolved: flag → INSTANCE_ID.
   --org-id=<value>       Organization ID. Required with --create when the token has multiple orgs.
   --project-id=<value>   Project ID. Required with --create.
+  --target=<value>       Store the link under targets.<name> in cli.yaml instead of the top-level fields. Select it
+                         later with --target or POWERSYNC_TARGET.
 
 PROJECT FLAGS
   --directory=<value>  [default: powersync] Directory containing PowerSync config. Defaults to "powersync". This is
@@ -1054,11 +1080,14 @@ DESCRIPTION
   [Cloud only] Link to a PowerSync Cloud instance (or create one with --create).
 
   Write or update cli.yaml with a Cloud instance. Use --create to create a new instance from service.yaml name/region
-  and link it; omit --instance-id when using --create.
+  and link it; omit --instance-id when using --create. Use --target to store the link as a named target, selected later
+  with --target or POWERSYNC_TARGET.
 
 EXAMPLES
   $ powersync link cloud --instance-id=<id>
 
+  $ powersync link cloud --target=staging --instance-id=<id>
+
   $ powersync link cloud --create --project-id=<project-id>
 
   $ powersync link cloud --create --project-id=<project-id> --org-id=<org-id>
@@ -1141,8 +1170,8 @@ Migrates Sync Rules to Sync Streams
 
 ```
 USAGE
-  $ powersync migrate sync-rules [--api-url <value> | --instance-id <value> |  | ] [--directory <value>] [--input-file
-    <value>] [--output-file <value>]
+  $ powersync migrate sync-rules [--target <value> | [--api-url <value> | --instance-id <value> |  | ] | ] [--directory
+    <value>] [--input-file <value>] [--output-file <value>]
 
 FLAGS
   --input-file=<value>   Path to the input sync rules file. Defaults to the project sync-config.yaml file.
@@ -1160,6 +1189,7 @@ PROJECT FLAGS
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  [Cloud] PowerSync Cloud instance ID (BSON ObjectID). When set, context is treated as cloud
                          (exclusive with --api-url). Resolved: flag → cli.yaml → INSTANCE_ID.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   Migrates Sync Rules to Sync Streams
@@ -1465,7 +1495,7 @@ _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/
 
 ```
 USAGE
-  $ powersync pull instance [--directory <value>] [--instance-id <value>] [--overwrite]
+  $ powersync pull instance [--directory <value>] [--target <value> | --instance-id <value>] [--overwrite]
 
 FLAGS
   --overwrite  Overwrite existing service.yaml and sync-config.yaml if they exist. By default, if these files already
@@ -1479,6 +1509,7 @@ PROJECT FLAGS
 
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  PowerSync Cloud instance ID. Manually passed if the current context has not been linked.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   [Cloud only] Pull an existing Cloud instance: link and download config into local service.yaml and sync-config.yaml.
@@ -1500,8 +1531,8 @@ Show instance diagnostics (connections, sync config, replication).
 
 ```
 USAGE
-  $ powersync status [--api-url <value> | --instance-id <value> |  | ] [--directory <value>] [--output
-    human|json|yaml]
+  $ powersync status [--target <value> | [--api-url <value> | --instance-id <value> |  | ] | ] [--directory
+    <value>] [--output human|json|yaml]
 
 FLAGS
   --output=<option>  [default: human] Output format: human-readable, json, or yaml.
@@ -1519,6 +1550,7 @@ PROJECT FLAGS
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  [Cloud] PowerSync Cloud instance ID (BSON ObjectID). When set, context is treated as cloud
                          (exclusive with --api-url). Resolved: flag → cli.yaml → INSTANCE_ID.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   Show instance diagnostics (connections, sync config, replication).
@@ -1542,7 +1574,7 @@ _See code: [src/commands/status.ts](https://github.com/powersync-ja/powersync-cl
 
 ```
 USAGE
-  $ powersync stop [--directory <value>] [--instance-id <value>] [--confirm yes]
+  $ powersync stop [--directory <value>] [--target <value> | --instance-id <value>] [--confirm yes]
 
 FLAGS
   --confirm=<option>  Set to "yes" to confirm stopping the instance.
@@ -1555,6 +1587,7 @@ PROJECT FLAGS
 
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  PowerSync Cloud instance ID. Manually passed if the current context has not been linked.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   [Cloud only] Stop the linked Cloud instance (restart with deploy).
@@ -1575,8 +1608,9 @@ Validate config schema, connections, and sync config before deploy.
 
 ```
 USAGE
-  $ powersync validate [--api-url <value> | --instance-id <value> |  | ] [--directory <value>]
-    [--sync-config-file-path <value>] [--output human|json|yaml] [--skip-validations <value> | --validate-only <value>]
+  $ powersync validate [--target <value> | [--api-url <value> | --instance-id <value> |  | ] | ] [--directory
+    <value>] [--sync-config-file-path <value>] [--output human|json|yaml] [--skip-validations <value> | --validate-only
+    <value>]
 
 FLAGS
   --output=<option>           [default: human] Output format: human-readable, json, or yaml.
@@ -1600,6 +1634,7 @@ PROJECT FLAGS
 CLOUD_PROJECT FLAGS
   --instance-id=<value>  [Cloud] PowerSync Cloud instance ID (BSON ObjectID). When set, context is treated as cloud
                          (exclusive with --api-url). Resolved: flag → cli.yaml → INSTANCE_ID.
+  --target=<value>       Name of a target defined in cli.yaml to run against. Resolved: flag → POWERSYNC_TARGET.
 
 DESCRIPTION
   Validate config schema, connections, and sync config before deploy.
diff --git a/cli/src/api/cloud/write-cloud-link.ts b/cli/src/api/cloud/write-cloud-link.ts
index 8c6e91fa..0be32e6a 100644
--- a/cli/src/api/cloud/write-cloud-link.ts
+++ b/cli/src/api/cloud/write-cloud-link.ts
@@ -7,23 +7,26 @@ export type WriteCloudLinkOptions = {
   instanceId: string;
   orgId: string;
   projectId: string;
+  /** Store the link under targets.<name> instead of the top-level fields. */
+  target?: string;
 };
 
 /**
- * Writes or updates cli.yaml with Cloud instance link (type: cloud, instance_id, org_id, project_id).
- * Creates a new file if it does not exist.
+ * Writes or updates cli.yaml with a Cloud instance link (type: cloud, instance_id, org_id, project_id),
+ * either at the top level or under a named target. Creates a new file if it does not exist.
  */
 export function writeCloudLink(projectDir: string, options: WriteCloudLinkOptions): void {
-  const { instanceId, orgId, projectId } = options;
+  const { instanceId, orgId, projectId, target } = options;
   const linkPath = join(projectDir, CLI_FILENAME);
   if (!existsSync(projectDir)) {
     mkdirSync(projectDir, { recursive: true });
   }
 
   const doc = existsSync(linkPath) ? parseYamlFile(linkPath) : new Document();
+  const basePath = target ? ['targets', target] : [];
   doc.set('type', 'cloud');
-  doc.set('instance_id', instanceId);
-  doc.set('org_id', orgId);
-  doc.set('project_id', projectId);
+  doc.setIn([...basePath, 'instance_id'], instanceId);
+  doc.setIn([...basePath, 'org_id'], orgId);
+  doc.setIn([...basePath, 'project_id'], projectId);
   writeFileSync(linkPath, doc.toString(), 'utf8');
 }
diff --git a/cli/src/commands/fetch/instances.ts b/cli/src/commands/fetch/instances.ts
index a4c329b0..333fe449 100644
--- a/cli/src/commands/fetch/instances.ts
+++ b/cli/src/commands/fetch/instances.ts
@@ -210,8 +210,16 @@ export default class FetchInstances extends Command {
         this.log(`Locally linked in ./${linked.subDirectory}/`);
         this.log(`\t${ux.colorize('blue', 'Project type: ')} ${linked.config.type}`);
         if (linked.config.type === 'cloud') {
-          this.log(`\t${ux.colorize('blue', 'Project ID: ')} ${linked.config.project_id}`);
-          this.log(`\t${ux.colorize('blue', 'Instance ID: ')} ${linked.config.instance_id}`);
+          if (linked.config.instance_id) {
+            this.log(`\t${ux.colorize('blue', 'Project ID: ')} ${linked.config.project_id}`);
+            this.log(`\t${ux.colorize('blue', 'Instance ID: ')} ${linked.config.instance_id}`);
+          }
+
+          for (const [name, target] of Object.entries(linked.config.targets ?? {})) {
+            this.log(
+              `\t${ux.colorize('blue', `Target ${name}: `)} ${ux.colorize('gray', `instance_id: ${target.instance_id}`)}`
+            );
+          }
         } else if (linked.config.type === 'self-hosted') {
           this.log(`\t${ux.colorize('blue', 'API URL: ')} ${linked.config.api_url}`);
         }
diff --git a/cli/src/commands/link/cloud.ts b/cli/src/commands/link/cloud.ts
index 19b43b10..7459d5a3 100644
--- a/cli/src/commands/link/cloud.ts
+++ b/cli/src/commands/link/cloud.ts
@@ -18,9 +18,10 @@ import { writeCloudLink } from '../../api/cloud/write-cloud-link.js';
 export default class LinkCloud extends CloudInstanceCommand {
   static commandHelpGroup = CommandHelpGroup.PROJECT_SETUP;
   static description =
-    'Write or update cli.yaml with a Cloud instance. Use --create to create a new instance from service.yaml name/region and link it; omit --instance-id when using --create.';
+    'Write or update cli.yaml with a Cloud instance. Use --create to create a new instance from service.yaml name/region and link it; omit --instance-id when using --create. Use --target to store the link as a named target, selected later with --target or POWERSYNC_TARGET.';
   static examples = [
     '<%= config.bin %> <%= command.id %> --instance-id=<id>',
+    '<%= config.bin %> <%= command.id %> --target=staging --instance-id=<id>',
     '<%= config.bin %> <%= command.id %> --create --project-id=<project-id>',
     '<%= config.bin %> <%= command.id %> --create --project-id=<project-id> --org-id=<org-id>'
   ];
@@ -32,7 +33,7 @@ export default class LinkCloud extends CloudInstanceCommand {
     }),
     'instance-id': Flags.string({
       default: env.INSTANCE_ID,
-      description: 'PowerSync Cloud instance ID. Omit when using --create. Resolved: flag → INSTANCE_ID → cli.yaml.',
+      description: 'PowerSync Cloud instance ID. Omit when using --create. Resolved: flag → INSTANCE_ID.',
       required: false
     }),
     'org-id': Flags.string({
@@ -44,15 +45,28 @@ export default class LinkCloud extends CloudInstanceCommand {
       default: env.PROJECT_ID,
       description: 'Project ID. Required with --create.',
       required: false
+    }),
+    target: Flags.string({
+      description: `Store the link under targets.<name> in ${CLI_FILENAME} instead of the top-level fields. Select it later with --target or POWERSYNC_TARGET.`,
+      required: false
     })
   };
   static summary = '[Cloud only] Link to a PowerSync Cloud instance (or create one with --create).';
 
   async run(): Promise<void> {
     const { flags } = await this.parse(LinkCloud);
-    let { create, directory, 'instance-id': instanceId, 'org-id': orgId, 'project-id': projectId } = flags;
+    let { create, directory, 'instance-id': instanceId, 'org-id': orgId, 'project-id': projectId, target } = flags;
+    const linkLabel = target ? ` (target "${target}")` : '';
 
     const projectDirectory = this.resolveProjectDir(flags);
+    ensureServiceTypeMatches({
+      command: this,
+      configRequired: create,
+      directoryLabel: directory,
+      expectedType: ServiceType.CLOUD,
+      projectDir: projectDirectory
+    });
+
     if (create) {
       if (instanceId) {
         this.styledError({
@@ -92,16 +106,17 @@ export default class LinkCloud extends CloudInstanceCommand {
         this.styledError({ error, message: 'Failed to create Cloud instance' });
       }
 
-      ensureServiceTypeMatches({
-        command: this,
-        configRequired: false,
-        directoryLabel: directory,
-        expectedType: ServiceType.CLOUD,
-        projectDir: projectDirectory
+      writeCloudLink(projectDirectory, {
+        instanceId: newInstanceId,
+        orgId: orgId!,
+        projectId: projectId!,
+        target
       });
-      writeCloudLink(projectDirectory, { instanceId: newInstanceId, orgId: orgId!, projectId: projectId! });
       this.log(
-        ux.colorize('green', `Created Cloud instance ${newInstanceId} and updated ${directory}/${CLI_FILENAME}.`)
+        ux.colorize(
+          'green',
+          `Created Cloud instance ${newInstanceId} and updated ${directory}/${CLI_FILENAME}${linkLabel}.`
+        )
       );
       return;
     }
@@ -130,19 +145,12 @@ export default class LinkCloud extends CloudInstanceCommand {
       this.styledError({ message: `Failed to resolve Cloud instance ${instanceId}.` });
     }
 
-    ensureServiceTypeMatches({
-      command: this,
-      configRequired: false,
-      directoryLabel: directory,
-      expectedType: ServiceType.CLOUD,
-      projectDir: projectDirectory
-    });
-
     writeCloudLink(projectDirectory, {
       instanceId: linked.instance_id,
       orgId: linked.org_id,
-      projectId: linked.project_id
+      projectId: linked.project_id,
+      target
     });
-    this.log(ux.colorize('green', `Updated ${directory}/${CLI_FILENAME} with Cloud instance link.`));
+    this.log(ux.colorize('green', `Updated ${directory}/${CLI_FILENAME} with Cloud instance link${linkLabel}.`));
   }
 }
diff --git a/cli/test/command-types/resolution-order.test.ts b/cli/test/command-types/resolution-order.test.ts
index 50dea8ef..6d0eb485 100644
--- a/cli/test/command-types/resolution-order.test.ts
+++ b/cli/test/command-types/resolution-order.test.ts
@@ -14,6 +14,7 @@ import { managementClientMock, MOCK_CLOUD_IDS } from '../setup.js';
 type EnvSnapshot = {
   API_URL: string | undefined;
   INSTANCE_ID: string | undefined;
+  POWERSYNC_TARGET: string | undefined;
   PS_ADMIN_TOKEN: string | undefined;
 };
 
@@ -59,6 +60,7 @@ describe('instance resolution order', () => {
     envSnapshot = {
       API_URL: env.API_URL,
       INSTANCE_ID: env.INSTANCE_ID,
+      POWERSYNC_TARGET: env.POWERSYNC_TARGET,
       PS_ADMIN_TOKEN: env.PS_ADMIN_TOKEN
     };
   });
@@ -67,6 +69,7 @@ describe('instance resolution order', () => {
     process.chdir(origCwd);
     env.API_URL = envSnapshot.API_URL;
     env.INSTANCE_ID = envSnapshot.INSTANCE_ID;
+    env.POWERSYNC_TARGET = envSnapshot.POWERSYNC_TARGET;
     env.PS_ADMIN_TOKEN = envSnapshot.PS_ADMIN_TOKEN;
     vi.restoreAllMocks();
     rmSync(tmpRoot, { force: true, recursive: true });
@@ -141,7 +144,89 @@ describe('instance resolution order', () => {
     );
 
     const { error } = await runDestroyDirect(['--confirm=yes']);
-    expect(error?.message).toContain('Invalid --instance-id');
+    expect(error?.message).toContain('Invalid instance_id in cli.yaml');
+  });
+
+  it('CloudInstanceCommand selects a cli.yaml target from --target or POWERSYNC_TARGET', async () => {
+    managementClientMock.getInstance.mockImplementation(({ id }: { id: string }) =>
+      Promise.resolve({ app_id: MOCK_CLOUD_IDS.projectId, id, org_id: MOCK_CLOUD_IDS.orgId })
+    );
+
+    const projectDir = join(tmpRoot, 'powersync');
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, 'service.yaml'), '_type: cloud\n', 'utf8');
+    writeFileSync(
+      join(projectDir, 'cli.yaml'),
+      [
+        'type: cloud',
+        `instance_id: ${IDS.cli.instance}`,
+        `org_id: ${IDS.cli.org}`,
+        `project_id: ${IDS.cli.project}`,
+        'targets:',
+        '  staging:',
+        `    instance_id: ${IDS.env.instance}`,
+        `    org_id: ${IDS.env.org}`,
+        `    project_id: ${IDS.env.project}`,
+        '  production:',
+        `    instance_id: ${IDS.flag.instance}`,
+        ''
+      ].join('\n'),
+      'utf8'
+    );
+
+    const loadProjectSpy = vi.spyOn(CloudInstanceCommand.prototype, 'loadProject');
+
+    // --target picks the named entry, including its org/project
+    await runDestroyDirect(['--confirm=yes', '--target=staging']);
+    const fromFlag = await loadProjectSpy.mock.results[0]!.value;
+    expect(fromFlag.target).toBe('staging');
+    expect(fromFlag.linked.instance_id).toBe(IDS.env.instance);
+    expect(fromFlag.linked.org_id).toBe(IDS.env.org);
+    expect(fromFlag.linked.project_id).toBe(IDS.env.project);
+
+    // POWERSYNC_TARGET selects an entry too; its missing org/project are resolved via getInstance
+    env.POWERSYNC_TARGET = 'production';
+    await runDestroyDirect(['--confirm=yes']);
+    const fromEnv = await loadProjectSpy.mock.results[1]!.value;
+    expect(fromEnv.target).toBe('production');
+    expect(fromEnv.linked.instance_id).toBe(IDS.flag.instance);
+    expect(fromEnv.linked.org_id).toBe(MOCK_CLOUD_IDS.orgId);
+    expect(fromEnv.linked.project_id).toBe(MOCK_CLOUD_IDS.projectId);
+
+    // --instance-id wins over the selected target and uses the top-level org/project
+    await runDestroyDirect(['--confirm=yes', `--instance-id=${IDS.env.instance}`]);
+    const fromInstanceFlag = await loadProjectSpy.mock.results[2]!.value;
+    expect(fromInstanceFlag.target).toBeUndefined();
+    expect(fromInstanceFlag.linked.instance_id).toBe(IDS.env.instance);
+    expect(fromInstanceFlag.linked.org_id).toBe(IDS.cli.org);
+    expect(fromInstanceFlag.linked.project_id).toBe(IDS.cli.project);
+  });
+
+  it('CloudInstanceCommand rejects an unknown target and --target combined with --instance-id', async () => {
+    const projectDir = join(tmpRoot, 'powersync');
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, 'service.yaml'), '_type: cloud\n', 'utf8');
+    writeFileSync(
+      join(projectDir, 'cli.yaml'),
+      ['type: cloud', 'targets:', '  staging:', `    instance_id: ${IDS.env.instance}`, ''].join('\n'),
+      'utf8'
+    );
+
+    const unknown = await runDestroyDirect(['--confirm=yes', '--target=production']);
+    expect(unknown.error?.message).toContain('Target "production" is not defined in cli.yaml');
+    expect(unknown.error?.message).toContain('staging');
+
+    // No default link and no selection: point at the targets that do exist
+    const unselected = await runDestroyDirect(['--confirm=yes']);
+    expect(unselected.error?.message).toContain('Linking is required');
+    expect(unselected.error?.suggestions?.[0]).toContain('--target or POWERSYNC_TARGET: staging');
+
+    const exclusive = await runDestroyDirect([
+      '--confirm=yes',
+      '--target=staging',
+      `--instance-id=${IDS.cli.instance}`
+    ]);
+    expect(exclusive.error?.message).toContain('cannot also be provided');
   });
 
   it('SharedInstanceCommand resolves self-hosted api_url as flag → cli.yaml → env', async () => {
@@ -181,6 +266,115 @@ describe('instance resolution order', () => {
     expect(fromEnv.linked.api_url).toBe('https://env.example.com');
   });
 
+  it('SharedInstanceCommand selects a cli.yaml target from --target or POWERSYNC_TARGET', async () => {
+    const projectDir = join(tmpRoot, 'powersync');
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, 'service.yaml'), '_type: cloud\n', 'utf8');
+    writeFileSync(
+      join(projectDir, 'cli.yaml'),
+      [
+        'type: cloud',
+        'targets:',
+        '  staging:',
+        `    instance_id: ${IDS.env.instance}`,
+        `    org_id: ${IDS.env.org}`,
+        `    project_id: ${IDS.env.project}`,
+        ''
+      ].join('\n'),
+      'utf8'
+    );
+
+    const loadProjectSpy = vi.spyOn(SharedInstanceCommand.prototype, 'loadProject');
+    vi.spyOn(FetchStatusCommand.prototype, 'getCloudStatus').mockRejectedValue(new Error('expected-test-failure'));
+
+    await runFetchStatusDirect(['--output=json', '--target=staging']);
+    const fromFlag = await loadProjectSpy.mock.results[0]!.value;
+    expect(fromFlag.target).toBe('staging');
+    expect(fromFlag.linked.type).toBe('cloud');
+    expect(fromFlag.linked.instance_id).toBe(IDS.env.instance);
+    expect(fromFlag.linked.org_id).toBe(IDS.env.org);
+    expect(fromFlag.linked.project_id).toBe(IDS.env.project);
+
+    env.POWERSYNC_TARGET = 'staging';
+    await runFetchStatusDirect(['--output=json']);
+    const fromEnv = await loadProjectSpy.mock.results[1]!.value;
+    expect(fromEnv.target).toBe('staging');
+    expect(fromEnv.linked.instance_id).toBe(IDS.env.instance);
+
+    env.POWERSYNC_TARGET = undefined;
+    const unselected = await runFetchStatusDirect(['--output=json']);
+    expect(unselected.error?.message).toContain('Linking is required');
+    expect(unselected.error?.suggestions?.[0]).toContain('--target or POWERSYNC_TARGET: staging');
+  });
+
+  it('SharedInstanceCommand lets --instance-id pick the cloud context over a self-hosted cli.yaml', async () => {
+    managementClientMock.getInstance.mockImplementation(({ id }: { id: string }) =>
+      Promise.resolve({ app_id: MOCK_CLOUD_IDS.projectId, id, org_id: MOCK_CLOUD_IDS.orgId })
+    );
+
+    const projectDir = join(tmpRoot, 'powersync');
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(
+      join(projectDir, 'cli.yaml'),
+      ['type: self-hosted', 'api_url: https://cli.example.com', 'api_key: cli-key', ''].join('\n'),
+      'utf8'
+    );
+
+    const loadProjectSpy = vi.spyOn(SharedInstanceCommand.prototype, 'loadProject');
+    vi.spyOn(FetchStatusCommand.prototype, 'getCloudStatus').mockRejectedValue(new Error('expected-test-failure'));
+
+    await runFetchStatusDirect(['--output=json', `--instance-id=${IDS.flag.instance}`]);
+    const project = await loadProjectSpy.mock.results[0]!.value;
+    expect(project.linked.type).toBe('cloud');
+    expect(project.linked.instance_id).toBe(IDS.flag.instance);
+  });
+
+  it('accepts a cli.yaml written by older CLI versions (no targets key)', async () => {
+    managementClientMock.getInstance.mockImplementation(({ id }: { id: string }) =>
+      Promise.resolve({ app_id: MOCK_CLOUD_IDS.projectId, id, org_id: MOCK_CLOUD_IDS.orgId })
+    );
+
+    const projectDir = join(tmpRoot, 'powersync');
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, 'service.yaml'), '_type: cloud\n', 'utf8');
+    writeFileSync(
+      join(projectDir, 'cli.yaml'),
+      [
+        '# yaml-language-server: $schema=https://unpkg.com/@powersync/cli-schemas@latest/json-schema/cli-config.json',
+        'type: cloud',
+        `instance_id: ${IDS.cli.instance}`,
+        `org_id: ${IDS.cli.org}`,
+        `project_id: ${IDS.cli.project}`,
+        ''
+      ].join('\n'),
+      'utf8'
+    );
+
+    const cloudSpy = vi.spyOn(CloudInstanceCommand.prototype, 'loadProject');
+    await runDestroyDirect(['--confirm=yes']);
+    const cloudProject = await cloudSpy.mock.results[0]!.value;
+    expect(cloudProject.target).toBeUndefined();
+    expect(cloudProject.linked).toEqual({
+      instance_id: IDS.cli.instance,
+      org_id: IDS.cli.org,
+      project_id: IDS.cli.project,
+      type: 'cloud'
+    });
+
+    const sharedSpy = vi.spyOn(SharedInstanceCommand.prototype, 'loadProject');
+    vi.spyOn(FetchStatusCommand.prototype, 'getCloudStatus').mockRejectedValue(new Error('expected-test-failure'));
+    await runFetchStatusDirect(['--output=json']);
+    const sharedProject = await sharedSpy.mock.results[0]!.value;
+    expect(sharedProject.target).toBeUndefined();
+    expect(sharedProject.linked.instance_id).toBe(IDS.cli.instance);
+
+    // Selecting a target on such a file explains how to add one
+    const { error } = await runDestroyDirect(['--confirm=yes', '--target=staging']);
+    expect(error?.message).toContain(
+      'Target "staging" is not defined in cli.yaml. Add it with: powersync link cloud --target=staging'
+    );
+  });
+
   it('SharedInstanceCommand resolves cloud instance_id as flag → cli.yaml → env; org/project from cli.yaml or API', async () => {
     // getInstance echoes the requested id so we can verify which instance was resolved
     managementClientMock.getInstance.mockImplementation(({ id }: { id: string }) =>
diff --git a/cli/test/commands/deploy.test.ts b/cli/test/commands/deploy.test.ts
index 53a9c5b8..27fef461 100644
--- a/cli/test/commands/deploy.test.ts
+++ b/cli/test/commands/deploy.test.ts
@@ -100,6 +100,16 @@ describe('deploy', () => {
     expect(result.error?.oclif?.exit).toBe(1);
   });
 
+  it('suggests pull instance when the directory is linked but has no service.yaml', async () => {
+    const projectDir = join(tmpDir, PROJECT_DIR);
+    mkdirSync(projectDir, { recursive: true });
+    writeLinkYaml(projectDir, { instance_id: INSTANCE_ID, org_id: ORG_ID, project_id: PROJECT_ID });
+    const result = await runCommand('deploy', { root });
+    expect(result.error?.message).toContain(`${SERVICE_FILENAME} in "./${PROJECT_DIR}/" is missing`);
+    expect(result.error?.suggestions?.[0]).toContain('powersync pull instance');
+    expect(result.error?.oclif?.exit).toBe(1);
+  });
+
   it('errors when cli.yaml does not exist', async () => {
     const projectDir = join(tmpDir, PROJECT_DIR);
     mkdirSync(projectDir, { recursive: true });
diff --git a/cli/test/commands/link.test.ts b/cli/test/commands/link.test.ts
index 16b452d6..49c3bb5f 100644
--- a/cli/test/commands/link.test.ts
+++ b/cli/test/commands/link.test.ts
@@ -151,6 +151,48 @@ describe('link', () => {
       expect(linkYaml.project_id).toBe(PROJECT_ID);
     });
 
+    it('creates cli.yaml with only a named target when --target is used in a new directory', async () => {
+      const { error } = await runLinkCloudDirect([
+        '--target=staging',
+        `--instance-id=${INSTANCE_ID}`,
+        `--org-id=${ORG_ID}`,
+        `--project-id=${PROJECT_ID}`
+      ]);
+      expect(error).toBeUndefined();
+      const linkYaml = parseYaml(readFileSync(join(tmpDir, PROJECT_DIR, CLI_FILENAME), 'utf8'));
+      expect(linkYaml).toEqual({
+        targets: { staging: { instance_id: INSTANCE_ID, org_id: ORG_ID, project_id: PROJECT_ID } },
+        type: 'cloud'
+      });
+    });
+
+    it('stores the link under a named target with --target', async () => {
+      const projectDir = join(tmpDir, PROJECT_DIR);
+      mkdirSync(projectDir, { recursive: true });
+      writeServiceYaml(projectDir, 'cloud');
+      const linkPath = join(projectDir, CLI_FILENAME);
+      writeFileSync(
+        linkPath,
+        `type: cloud\ninstance_id: ${INSTANCE_ID}\norg_id: ${ORG_ID}\nproject_id: ${PROJECT_ID}\n`,
+        'utf8'
+      );
+      const stagingInstanceId = '690cf75c96a2ff4fd98b160b';
+
+      const { error, stdout } = await runLinkCloudDirect([
+        '--target=staging',
+        `--instance-id=${stagingInstanceId}`,
+        `--org-id=${ORG_ID}`,
+        `--project-id=${PROJECT_ID}`
+      ]);
+      expect(error).toBeUndefined();
+      expect(stdout).toContain(`Updated ${PROJECT_DIR}/${CLI_FILENAME} with Cloud instance link (target "staging").`);
+      const linkYaml = parseYaml(readFileSync(linkPath, 'utf8'));
+      expect(linkYaml.instance_id).toBe(INSTANCE_ID);
+      expect(linkYaml.targets).toEqual({
+        staging: { instance_id: stagingInstanceId, org_id: ORG_ID, project_id: PROJECT_ID }
+      });
+    });
+
     it('creates and links cloud instance when directory exists and --create is used', async () => {
       const projectDir = join(tmpDir, PROJECT_DIR);
       mkdirSync(projectDir, { recursive: true });
@@ -176,6 +218,31 @@ describe('link', () => {
       expect(linkYaml.project_id).toBe(PROJECT_ID);
     });
 
+    it('creates a cloud instance and stores the link under a named target with --create --target', async () => {
+      const projectDir = join(tmpDir, PROJECT_DIR);
+      mkdirSync(projectDir, { recursive: true });
+      writeValidCloudServiceYaml(projectDir);
+      managementClientMock.listRegions.mockResolvedValueOnce({ regions: [{ name: 'us' }] });
+      managementClientMock.createInstance.mockResolvedValueOnce({ id: INSTANCE_ID });
+
+      const { error, stdout } = await runLinkCloudDirect([
+        '--create',
+        '--target=staging',
+        `--org-id=${ORG_ID}`,
+        `--project-id=${PROJECT_ID}`
+      ]);
+
+      expect(error).toBeUndefined();
+      expect(stdout).toContain(
+        `Created Cloud instance ${INSTANCE_ID} and updated ${PROJECT_DIR}/${CLI_FILENAME} (target "staging").`
+      );
+      const linkYaml = parseYaml(readFileSync(join(tmpDir, PROJECT_DIR, CLI_FILENAME), 'utf8'));
+      expect(linkYaml).toEqual({
+        targets: { staging: { instance_id: INSTANCE_ID, org_id: ORG_ID, project_id: PROJECT_ID } },
+        type: 'cloud'
+      });
+    });
+
     it('updates existing cli.yaml and preserves comments', async () => {
       const projectDir = join(tmpDir, PROJECT_DIR);
       mkdirSync(projectDir, { recursive: true });
diff --git a/cli/test/setup.ts b/cli/test/setup.ts
index a8fd6010..d4a7f909 100644
--- a/cli/test/setup.ts
+++ b/cli/test/setup.ts
@@ -4,6 +4,7 @@ import { vi } from 'vitest';
 // Normalize env so tests don't inherit real linking values
 delete process.env.INSTANCE_ID;
 delete process.env.ORG_ID;
+delete process.env.POWERSYNC_TARGET;
 delete process.env.PROJECT_ID;
 
 export const MOCK_CLOUD_IDS = {
diff --git a/docs/cli-documentation-conventions.md b/docs/cli-documentation-conventions.md
index 5550fa1b..60b74b33 100644
--- a/docs/cli-documentation-conventions.md
+++ b/docs/cli-documentation-conventions.md
@@ -27,7 +27,7 @@ For grouped commands (e.g. `fetch`, `generate`, `init`, `link`, `pull`, `migrate
 ## README
 
 - The CLI README (`cli/README.md`) uses oclif markers: `<!-- toc -->`, `<!-- usage -->`, `<!-- commands -->`. Content between these is replaced by `oclif readme` (run on `prepack` and `version`). Do not hand-edit the generated command blocks.
-- An **Environment variables** section (after the usage block) documents `PS_ADMIN_TOKEN`, `INSTANCE_ID`, and `API_URL` for script/CI use, with a short example.
+- An **Environment variables** section (after the usage block) documents `PS_ADMIN_TOKEN`, `INSTANCE_ID`, `POWERSYNC_TARGET`, and `API_URL` for script/CI use, with a short example.
 
 ## Regenerating command docs
 
diff --git a/docs/usage.md b/docs/usage.md
index a4e2da34..23c6e794 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -43,6 +43,50 @@ powersync deploy service-config --directory=powersync   # service.yaml only (kee
 powersync deploy sync-config --directory=powersync      # sync-config.yaml only
 ```
 
+**Named targets in one `cli.yaml`**
+
+Targets let one config directory point at several Cloud instances, for example staging and production. Each target is an entry under `targets` in `cli.yaml` with its own instance, org and project IDs. The top-level fields stay the default when no target is selected.
+
+Create a target by linking an existing instance to a name:
+
+```bash
+powersync fetch instances # find the instance ID
+powersync link cloud --target=staging --instance-id=<staging instance id>
+```
+
+Or create a new instance and link it in one step. The instance name and region come from `service.yaml`:
+
+```bash
+powersync link cloud --create --target=staging --project-id=<project id>
+```
+
+Either way, `cli.yaml` ends up like this:
+
+```yaml
+type: cloud
+instance_id: <production instance id> # default target
+org_id: <org id>
+project_id: <project id>
+targets:
+  staging:
+    instance_id: <staging instance id>
+    org_id: <org id>
+    project_id: <project id>
+```
+
+Use a target by passing `--target` to any cloud command, or set `POWERSYNC_TARGET` for scripts and CI:
+
+```bash
+powersync pull instance --target=staging # download its service.yaml and sync-config.yaml
+powersync deploy --target=staging
+powersync status --target=staging
+POWERSYNC_TARGET=staging powersync deploy sync-config
+```
+
+Commands without `--target` or `POWERSYNC_TARGET` use the top-level fields. `--instance-id` overrides both. Every cloud command prints the target instance name and IDs, and the selected target, before it makes changes, and `powersync fetch instances` lists the targets of each linked directory.
+
+Deploy writes the `name` from `service.yaml` to the instance, so instances deployed from one `service.yaml` end up with the same name in the dashboard.
+
 **Alternate sync config file**
 
 These commands accept **`--sync-config-file-path=/path/to/sync.yaml`** instead of **`sync-config.yaml`** in the project directory: **`powersync deploy`**, **`powersync deploy sync-config`**, **`powersync validate`**, **`powersync generate schema`**. Other commands (e.g. **`deploy service-config`**, **`generate token`**, **`destroy`**, **`status`**) do not expose this flag.
@@ -223,15 +267,15 @@ If you decline this prompt, login exits without storing a token. Use `PS_ADMIN_T
 
 # Supplying Linking Information for Cloud and Self-Hosted Commands
 
-Cloud and self-hosted commands need an instance identifier. **Cloud only:** `powersync deploy`, `powersync deploy service-config`, `powersync deploy sync-config`, `powersync destroy`, `powersync stop`, `powersync fetch config`, `powersync pull instance`. **Both:** `powersync status`, `powersync generate schema`, `powersync generate token`, `powersync validate`. The same three methods apply: the CLI uses the first that is available (flags override environment variables, environment variables override link file). For Cloud commands, the org and project are resolved automatically from the instance.
+Cloud and self-hosted commands need an instance identifier. **Cloud only:** `powersync deploy`, `powersync deploy service-config`, `powersync deploy sync-config`, `powersync destroy`, `powersync stop`, `powersync fetch config`, `powersync pull instance`. **Both:** `powersync status`, `powersync generate schema`, `powersync generate token`, `powersync validate`. The same three methods apply: the CLI uses the first that is available (flags override the link file, and the link file overrides environment variables). For Cloud commands, the org and project are resolved automatically from the instance.
 
 1. **Flags**
-   - **Cloud:** `--instance-id`
+   - **Cloud:** `--instance-id`, or `--target` to pick a named target from `cli.yaml`
    - **Self-hosted:** `--api-url` only (API key from env or link file only)
-2. **Environment variables**
-   - **Cloud:** `INSTANCE_ID`
+2. **cli.yaml** — a `powersync/cli.yaml` file in the project (written by `powersync link cloud` or `powersync link self-hosted`)
+3. **Environment variables**
+   - **Cloud:** `INSTANCE_ID`, or `POWERSYNC_TARGET` to pick a named target from `cli.yaml`
    - **Self-hosted:** `API_URL`, `PS_ADMIN_TOKEN` (API key)
-3. **cli.yaml** — a `powersync/cli.yaml` file in the project (written by `powersync link cloud` or `powersync link self-hosted`)
 
 ---
 
@@ -246,6 +290,9 @@ powersync login
 
 # Stop a specific instance without linking the directory (overrides cli.yaml if present)
 powersync stop --confirm=yes --instance-id=688736sdfcfb46688f509bd0
+
+# Or pick a named target from cli.yaml
+powersync stop --confirm=yes --target=staging
 ```
 
 **Self-hosted:** Set `PS_ADMIN_TOKEN` (or use a linked project with API key in cli.yaml), then:
@@ -301,6 +348,9 @@ export INSTANCE_ID=688736sdfcfb46688f509bd0
 
 powersync stop --confirm=yes
 powersync fetch config --output=json
+
+# Or pick a named target from cli.yaml
+POWERSYNC_TARGET=staging powersync deploy
 ```
 
 **Self-hosted:**
diff --git a/packages/cli-core/src/command-types/CloudInstanceCommand.ts b/packages/cli-core/src/command-types/CloudInstanceCommand.ts
index 8d187864..abe468e7 100644
--- a/packages/cli-core/src/command-types/CloudInstanceCommand.ts
+++ b/packages/cli-core/src/command-types/CloudInstanceCommand.ts
@@ -1,5 +1,6 @@
 import { Flags, Interfaces, ux } from '@oclif/core';
 import {
+  CloudCLIConfig,
   ResolvedCloudCLIConfig,
   ServiceCloudConfig,
   ServiceCloudConfigDecoded,
@@ -10,6 +11,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { createCloudClient } from '../clients/create-cloud-client.js';
+import { createTargetFlag } from '../utils/create-target-flag.js';
 import { ensureServiceTypeMatches, ServiceType } from '../utils/ensure-service-type.js';
 import { env } from '../utils/env.js';
 import { LINK_MISSING_ERROR_MESSAGE } from '../utils/errors.js';
@@ -18,6 +20,7 @@ import { OBJECT_ID_REGEX } from '../utils/object-id.js';
 import { CLI_FILENAME, SERVICE_FILENAME } from '../utils/project-config.js';
 import { resolveCloudInstanceLink } from '../utils/resolve-cloud-instance-link.js';
 import { resolveSyncRulesContent } from '../utils/resolve-sync-rules-content.js';
+import { CloudLink, selectCloudLink, suggestTargets } from '../utils/select-cloud-link.js';
 import { parseYamlFile } from '../utils/yaml.js';
 import { CommandHelpGroup, HelpGroup } from './HelpGroup.js';
 import { DEFAULT_ENSURE_CONFIG_OPTIONS, EnsureConfigOptions, InstanceCommand } from './InstanceCommand.js';
@@ -26,6 +29,8 @@ export type CloudProject = {
   linked: ResolvedCloudCLIConfig;
   projectDirectory: string;
   syncRulesContent?: string;
+  /** Name of the cli.yaml target the link was selected from, if any. */
+  target?: string;
 };
 
 /**
@@ -40,14 +45,17 @@ export type CloudInstanceCommandFlags = Interfaces.InferredFlags<
  * Base command for operations that require a Cloud-type PowerSync project (service.yaml _type: cloud).
  *
  * Instance context (instance_id, org_id, project_id) is resolved in this order:
- * 1. Command-line flags (--instance-id, --org-id, --project-id)
- * 2. Linked config from cli.yaml
- * 3. Environment variables (INSTANCE_ID, ORG_ID, PROJECT_ID)
- * 4. If org_id or project_id is still missing: resolve it from the Cloud instance.
+ * 1. --instance-id
+ * 2. The cli.yaml target selected with --target or POWERSYNC_TARGET
+ * 3. The top-level fields in cli.yaml
+ * 4. INSTANCE_ID
+ * 5. If org_id or project_id is still missing: resolve it from the Cloud instance.
  *
  * @example
  * # Use linked project (cli.yaml)
  * pnpm exec powersync some-cloud-cmd
+ * # Use a named target from cli.yaml
+ * pnpm exec powersync some-cloud-cmd --target=staging
  * # Override with env
  * INSTANCE_ID=... pnpm exec powersync some-cloud-cmd
  * # Override with flags
@@ -56,7 +64,7 @@ export type CloudInstanceCommandFlags = Interfaces.InferredFlags<
 export abstract class CloudInstanceCommand extends InstanceCommand {
   static baseFlags = {
     /**
-     * Instance ID, org ID, and project ID are resolved in order: flags → cli.yaml → env (INSTANCE_ID, ORG_ID, PROJECT_ID).
+     * Instance ID, org ID, and project ID are resolved in order: flags → cli.yaml (selected target, then top-level fields) → INSTANCE_ID.
      * Missing org/project IDs are resolved from the Cloud instance.
      */
     ...InstanceCommand.baseFlags,
@@ -82,7 +90,8 @@ export abstract class CloudInstanceCommand extends InstanceCommand {
       helpGroup: HelpGroup.CLOUD_PROJECT,
       hidden: true,
       required: false
-    })
+    }),
+    target: createTargetFlag({ exclusive: ['instance-id'] })
   };
   static commandHelpGroup = CommandHelpGroup.CLOUD;
   protected _project: CloudProject | null = null;
@@ -149,54 +158,53 @@ export abstract class CloudInstanceCommand extends InstanceCommand {
 
     const linkPath = join(projectDir, CLI_FILENAME);
 
-    let linked: null | ResolvedCloudCLIConfig = null;
-    let rawLink: null | Record<string, unknown> = null;
-
+    let cliConfig: CloudCLIConfig | null = null;
     if (existsSync(linkPath)) {
       try {
-        const doc = parseYamlFile(linkPath);
-        rawLink = doc.contents?.toJSON() as Record<string, unknown>;
+        cliConfig = CloudCLIConfig.decode(parseYamlFile(linkPath).contents?.toJSON());
       } catch (error) {
-        this.styledError({
-          error,
-          message: `Failed to parse ${CLI_FILENAME} as CloudCLIConfig`
-        });
+        this.styledError({ error, message: `Failed to parse ${CLI_FILENAME} as CloudCLIConfig` });
       }
     }
 
-    // Only instance_id is accepted as a CLI flag - project_id and org_id overrides must come from cli.yaml
-    const instance_id = flags['instance-id'] ?? (rawLink?.instance_id as string | undefined) ?? env.INSTANCE_ID;
-    const project_id = rawLink?.project_id as string | undefined;
-    const org_id = rawLink?.org_id as string | undefined;
+    const instanceIdFlag = flags['instance-id'];
+    // --instance-id points at one instance directly, so a selected target does not apply.
+    const target = instanceIdFlag ? undefined : (flags.target ?? env.POWERSYNC_TARGET);
 
-    if (instance_id != null || project_id != null || org_id != null) {
-      this.ensureObjectIdIfPresent(instance_id, '--instance-id');
-      this.ensureObjectIdIfPresent(org_id, '--org-id');
-      this.ensureObjectIdIfPresent(project_id, '--project-id');
-
-      if (!instance_id) {
-        this.styledError({ message: LINK_MISSING_ERROR_MESSAGE });
-      }
+    let link: CloudLink;
+    try {
+      link = selectCloudLink(cliConfig, target);
+    } catch (error) {
+      this.styledError({ message: error instanceof Error ? error.message : String(error) });
+    }
 
-      try {
-        linked = ResolvedCloudCLIConfig.decode(
-          await resolveCloudInstanceLink({
-            client: this.client,
-            instanceId: instance_id,
-            orgId: org_id,
-            projectId: project_id
-          })
-        );
-      } catch (error) {
-        this.styledError({ error, message: LINK_MISSING_ERROR_MESSAGE });
-      }
+    const instance_id = instanceIdFlag ?? link.instance_id ?? env.INSTANCE_ID;
+    if (!instance_id) {
+      this.styledError({ message: LINK_MISSING_ERROR_MESSAGE, suggestions: suggestTargets(cliConfig) });
     }
 
-    if (!linked) {
-      this.styledError({
-        message:
-          'Linking is required before using this command. No linking information was found in the current context.'
-      });
+    const linkField = (field: string) => `${target ? `targets.${target}.${field}` : field} in ${CLI_FILENAME}`;
+    const instanceIdSource = instanceIdFlag
+      ? '--instance-id'
+      : link.instance_id
+        ? linkField('instance_id')
+        : 'INSTANCE_ID';
+    this.ensureObjectIdIfPresent(instance_id, instanceIdSource);
+    this.ensureObjectIdIfPresent(link.org_id, linkField('org_id'));
+    this.ensureObjectIdIfPresent(link.project_id, linkField('project_id'));
+
+    let linked: ResolvedCloudCLIConfig;
+    try {
+      linked = ResolvedCloudCLIConfig.decode(
+        await resolveCloudInstanceLink({
+          client: this.client,
+          instanceId: instance_id,
+          orgId: link.org_id,
+          projectId: link.project_id
+        })
+      );
+    } catch (error) {
+      this.styledError({ error, message: LINK_MISSING_ERROR_MESSAGE });
     }
 
     const syncRulesContent = resolveSyncRulesContent({ projectDirectory: projectDir });
@@ -204,7 +212,8 @@ export abstract class CloudInstanceCommand extends InstanceCommand {
     this._project = await this._loadProjectHook(flags, {
       linked,
       projectDirectory: projectDir,
-      syncRulesContent
+      syncRulesContent,
+      target: link.target
     });
 
     return this._project;
@@ -237,18 +246,9 @@ export abstract class CloudInstanceCommand extends InstanceCommand {
     return this.serviceConfig;
   }
 
-  private ensureObjectIdIfPresent(
-    value: string | undefined,
-    flagName: '--instance-id' | '--org-id' | '--project-id'
-  ): void {
-    if (value == null) {
-      return;
-    }
-
-    if (!OBJECT_ID_REGEX.test(value)) {
-      this.styledError({
-        message: `Invalid ${flagName} "${value}". Expected a BSON ObjectID (24 hex characters).`
-      });
+  private ensureObjectIdIfPresent(value: string | undefined, label: string): void {
+    if (value != null && !OBJECT_ID_REGEX.test(value)) {
+      this.styledError({ message: `Invalid ${label} "${value}". Expected a BSON ObjectID (24 hex characters).` });
     }
   }
 }
diff --git a/packages/cli-core/src/command-types/SharedInstanceCommand.ts b/packages/cli-core/src/command-types/SharedInstanceCommand.ts
index afc01229..c8380b70 100644
--- a/packages/cli-core/src/command-types/SharedInstanceCommand.ts
+++ b/packages/cli-core/src/command-types/SharedInstanceCommand.ts
@@ -17,6 +17,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { createCloudClient } from '../clients/create-cloud-client.js';
+import { createTargetFlag } from '../utils/create-target-flag.js';
 import { ensureServiceTypeMatches, ServiceType } from '../utils/ensure-service-type.js';
 import { env } from '../utils/env.js';
 import { LINK_MISSING_ERROR_MESSAGE } from '../utils/errors.js';
@@ -24,6 +25,7 @@ import { logTargetInstance } from '../utils/log-target-instance.js';
 import { CLI_FILENAME, SERVICE_FILENAME } from '../utils/project-config.js';
 import { resolveCloudInstanceLink } from '../utils/resolve-cloud-instance-link.js';
 import { resolveSyncRulesContent } from '../utils/resolve-sync-rules-content.js';
+import { CloudLink, selectCloudLink, suggestTargets } from '../utils/select-cloud-link.js';
 import { parseYamlFile } from '../utils/yaml.js';
 import { CloudProject } from './CloudInstanceCommand.js';
 import { CommandHelpGroup, HelpGroup } from './HelpGroup.js';
@@ -45,7 +47,7 @@ export type SharedInstanceCommandFlags = Interfaces.InferredFlags<
  *    - Then from environment variables.
  *
  * 2. **Per-field values** (instance_id, org_id, project_id for cloud; api_url, api_key for self-hosted):
- *    - Cloud: flags → cli.yaml → env.
+ *    - Cloud: flags → cli.yaml (target selected with --target or POWERSYNC_TARGET, then top-level fields) → env.
  *    - Self-hosted: api_url from flag → cli.yaml → env; api_key from env → cli.yaml only (no flag).
  *
  * @example
@@ -92,6 +94,7 @@ export abstract class SharedInstanceCommand extends InstanceCommand {
       hidden: true,
       required: false
     }),
+    target: createTargetFlag({ exclusive: ['api-url', 'instance-id'] }),
     ...InstanceCommand.baseFlags
   };
   static commandHelpGroup = CommandHelpGroup.INSTANCE;
@@ -135,7 +138,7 @@ export abstract class SharedInstanceCommand extends InstanceCommand {
     const linkPath = join(projectDir, CLI_FILENAME);
 
     // 1) Context type: flags first, then link file, then env (see class JSDoc for resolution order).
-    const hasCloudFlagInputs = flags['instance-id'];
+    const hasCloudFlagInputs = flags['instance-id'] ?? flags.target;
     const hasSelfHostedFlagInputs = flags['api-url'];
 
     if (hasCloudFlagInputs && hasSelfHostedFlagInputs) {
@@ -151,18 +154,18 @@ export abstract class SharedInstanceCommand extends InstanceCommand {
     // If type not set by flags, use link file type (if present).
     let rawCLIConfig: CLIConfig | null = null;
     if (existsSync(linkPath)) {
-      const doc = parseYamlFile(linkPath);
-      rawCLIConfig = CLIConfig.decode(doc.contents?.toJSON());
-      if (rawCLIConfig.type === 'self-hosted') {
-        projectType = ServiceType.SELF_HOSTED;
-      } else if (rawCLIConfig.type === 'cloud') {
-        projectType = ServiceType.CLOUD;
+      try {
+        rawCLIConfig = CLIConfig.decode(parseYamlFile(linkPath).contents?.toJSON());
+      } catch (error) {
+        this.styledError({ error, message: `Failed to parse ${CLI_FILENAME}` });
       }
+
+      projectType ??= rawCLIConfig.type === 'self-hosted' ? ServiceType.SELF_HOSTED : ServiceType.CLOUD;
     }
 
     // If type still not set, use env inputs.
     if (!projectType) {
-      const hasCloudEnvInputs = env.INSTANCE_ID;
+      const hasCloudEnvInputs = env.INSTANCE_ID ?? env.POWERSYNC_TARGET;
       const hasSelfHostedEnvInputs = env.API_URL;
 
       if (hasCloudEnvInputs && hasSelfHostedEnvInputs) {
@@ -179,6 +182,7 @@ export abstract class SharedInstanceCommand extends InstanceCommand {
 
     // 2) Per-field: flags → link file → env (see class JSDoc).
     let cliConfig: null | ResolvedCloudCLIConfig | ResolvedSelfHostedCLIConfig = null;
+    let link: CloudLink | undefined;
     if (projectType === 'self-hosted') {
       const _rawSelfHostedCLIConfig = (rawCLIConfig as SelfHostedCLIConfig) ?? { type: 'self-hosted' };
       try {
@@ -191,10 +195,18 @@ export abstract class SharedInstanceCommand extends InstanceCommand {
         this.styledError({ error, message: LINK_MISSING_ERROR_MESSAGE });
       }
     } else {
-      const _rawCloudCLIConfig = (rawCLIConfig as CloudCLIConfig) ?? { type: 'cloud' };
-      const instanceId = flags['instance-id'] ?? _rawCloudCLIConfig.instance_id ?? env.INSTANCE_ID;
+      // --instance-id points at one instance directly, so a selected target does not apply.
+      const target = flags['instance-id'] ? undefined : (flags.target ?? env.POWERSYNC_TARGET);
+      const rawCloudCLIConfig = rawCLIConfig as CloudCLIConfig | null;
+      try {
+        link = selectCloudLink(rawCloudCLIConfig, target);
+      } catch (error) {
+        this.styledError({ message: error instanceof Error ? error.message : String(error) });
+      }
+
+      const instanceId = flags['instance-id'] ?? link.instance_id ?? env.INSTANCE_ID;
       if (!instanceId) {
-        this.styledError({ message: LINK_MISSING_ERROR_MESSAGE });
+        this.styledError({ message: LINK_MISSING_ERROR_MESSAGE, suggestions: suggestTargets(rawCloudCLIConfig) });
       }
 
       try {
@@ -203,8 +215,8 @@ export abstract class SharedInstanceCommand extends InstanceCommand {
             client: this.cloudClient,
             instanceId,
             // orgId and projectId can either be set via cli.yaml or resolved via instanceId
-            orgId: _rawCloudCLIConfig.org_id,
-            projectId: _rawCloudCLIConfig.project_id
+            orgId: link.org_id,
+            projectId: link.project_id
           })
         );
       } catch (error) {
@@ -220,7 +232,7 @@ export abstract class SharedInstanceCommand extends InstanceCommand {
     ensureServiceTypeMatches({
       command: this,
       configRequired: false,
-      directoryLabel: projectDir,
+      directoryLabel: flags.directory,
       expectedType: projectType!,
       projectDir
     });
@@ -237,7 +249,8 @@ export abstract class SharedInstanceCommand extends InstanceCommand {
       return this._loadProjectHook(flags, {
         linked: cliConfig as ResolvedCloudCLIConfig,
         projectDirectory: projectDir,
-        syncRulesContent
+        syncRulesContent,
+        target: link?.target
       });
     }
 
diff --git a/packages/cli-core/src/index.ts b/packages/cli-core/src/index.ts
index ffd991be..e8e1ffff 100644
--- a/packages/cli-core/src/index.ts
+++ b/packages/cli-core/src/index.ts
@@ -19,6 +19,7 @@ export * from './services/authentication/AuthenticationServiceImpl.js';
 export * from './services/Services.js';
 export * from './services/storage/StorageImp.js';
 export * from './services/storage/StorageService.js';
+export * from './utils/create-target-flag.js';
 export * from './utils/ensure-service-type.js';
 export * from './utils/env.js';
 export * from './utils/log-target-instance.js';
@@ -26,5 +27,6 @@ export * from './utils/object-id.js';
 export * from './utils/project-config.js';
 export * from './utils/resolve-cloud-instance-link.js';
 export * from './utils/resolve-sync-rules-content.js';
+export * from './utils/select-cloud-link.js';
 export * from './utils/sync-config-file-path-flags.js';
 export * from './utils/yaml.js';
diff --git a/packages/cli-core/src/utils/create-target-flag.ts b/packages/cli-core/src/utils/create-target-flag.ts
new file mode 100644
index 00000000..cccb2810
--- /dev/null
+++ b/packages/cli-core/src/utils/create-target-flag.ts
@@ -0,0 +1,18 @@
+import { Flags } from '@oclif/core';
+
+import { HelpGroup } from '../command-types/HelpGroup.js';
+import { CLI_FILENAME } from './project-config.js';
+
+export type TargetFlagOptions = {
+  /** Flags that cannot be combined with --target, such as --instance-id. */
+  exclusive: string[];
+};
+
+export function createTargetFlag(options: TargetFlagOptions) {
+  return Flags.string({
+    description: `Name of a target defined in ${CLI_FILENAME} to run against. Resolved: flag → POWERSYNC_TARGET.`,
+    exclusive: options.exclusive,
+    helpGroup: HelpGroup.CLOUD_PROJECT,
+    required: false
+  });
+}
diff --git a/packages/cli-core/src/utils/ensure-service-type.ts b/packages/cli-core/src/utils/ensure-service-type.ts
index 55a0c217..a823437f 100644
--- a/packages/cli-core/src/utils/ensure-service-type.ts
+++ b/packages/cli-core/src/utils/ensure-service-type.ts
@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { PowerSyncCommand } from '../command-types/PowerSyncCommand.js';
-import { SERVICE_FILENAME } from './project-config.js';
+import { CLI_FILENAME, SERVICE_FILENAME } from './project-config.js';
 import { parseYamlFile } from './yaml.js';
 
 export enum ServiceType {
@@ -28,8 +28,16 @@ export function ensureServiceTypeMatches(options: EnsureServiceTypeMatchesOption
 
   if (!existsSync(servicePath)) {
     if (configRequired) {
+      // A linked Cloud directory without config usually just needs its config pulled.
+      const linkedCloud = expectedType === ServiceType.CLOUD && existsSync(join(projectDir, CLI_FILENAME));
       command.styledError({
-        message: `${SERVICE_FILENAME} in "./${directoryLabel}/" is missing. Ensure it exists and has \`_type: ${expectedType}\`. Use ${ux.colorize('blue', `powersync init ${expectedType}`)} to create a project of the correct type.`
+        message: `${SERVICE_FILENAME} in "./${directoryLabel}/" is missing. Ensure it exists and has \`_type: ${expectedType}\`.`,
+        suggestions: [
+          ...(linkedCloud
+            ? [`Run ${ux.colorize('blue', 'powersync pull instance')} to download the linked instance's config.`]
+            : []),
+          `Use ${ux.colorize('blue', `powersync init ${expectedType}`)} to create a project of the correct type.`
+        ]
       });
     }
 
diff --git a/packages/cli-core/src/utils/env.ts b/packages/cli-core/src/utils/env.ts
index e49cc3a1..87cfa7d5 100644
--- a/packages/cli-core/src/utils/env.ts
+++ b/packages/cli-core/src/utils/env.ts
@@ -9,6 +9,7 @@ export type ENV = {
   API_URL?: string;
   INSTANCE_ID?: string;
   ORG_ID?: string;
+  POWERSYNC_TARGET?: string;
   PROJECT_ID?: string;
   PS_ADMIN_TOKEN?: string;
 };
@@ -20,6 +21,7 @@ export const env: ENV = {
   API_URL: process.env.API_URL,
   INSTANCE_ID: process.env.INSTANCE_ID,
   ORG_ID: process.env.ORG_ID,
+  POWERSYNC_TARGET: process.env.POWERSYNC_TARGET,
   PROJECT_ID: process.env.PROJECT_ID,
   PS_ADMIN_TOKEN: process.env.PS_ADMIN_TOKEN
 };
diff --git a/packages/cli-core/src/utils/log-target-instance.ts b/packages/cli-core/src/utils/log-target-instance.ts
index 053a5928..8cfa5ddf 100644
--- a/packages/cli-core/src/utils/log-target-instance.ts
+++ b/packages/cli-core/src/utils/log-target-instance.ts
@@ -42,7 +42,9 @@ export async function logTargetInstance(params: LogTargetInstanceParams): Promis
 
   const nameLabel =
     instanceName == null ? ux.colorize('yellow', '(name unavailable)') : ux.colorize('blue', instanceName);
-  command.log(`Target instance: ${nameLabel} ${ux.colorize('gray', `id: ${linked.instance_id}`)}`);
+  const target = 'target' in project ? project.target : undefined;
+  const targetLabel = target ? ` ${ux.colorize('gray', `target: ${target}`)}` : '';
+  command.log(`Target instance: ${nameLabel} ${ux.colorize('gray', `id: ${linked.instance_id}`)}${targetLabel}`);
   command.log(
     `\t${ux.colorize('gray', `project: ${linked.project_id}`)} ${ux.colorize('gray', `org: ${linked.org_id}`)}`
   );
diff --git a/packages/cli-core/src/utils/select-cloud-link.ts b/packages/cli-core/src/utils/select-cloud-link.ts
new file mode 100644
index 00000000..f1dc9005
--- /dev/null
+++ b/packages/cli-core/src/utils/select-cloud-link.ts
@@ -0,0 +1,36 @@
+import { CloudCLIConfig, CloudTargetConfig } from '@powersync/cli-schemas';
+
+import { CLI_FILENAME } from './project-config.js';
+
+export type CloudLink = Partial<CloudTargetConfig> & { target?: string };
+
+/**
+ * Picks the link fields a Cloud command should use: the named target when one is selected,
+ * otherwise the top-level fields of cli.yaml.
+ */
+export function selectCloudLink(cliConfig: CloudCLIConfig | null, target?: string): CloudLink {
+  if (target == null) {
+    return { instance_id: cliConfig?.instance_id, org_id: cliConfig?.org_id, project_id: cliConfig?.project_id };
+  }
+
+  const targets = cliConfig?.targets ?? {};
+  const link = Object.hasOwn(targets, target) ? targets[target] : undefined;
+  if (!link) {
+    const available = Object.keys(targets);
+    throw new Error(
+      available.length > 0
+        ? `Target "${target}" is not defined in ${CLI_FILENAME}. Available targets: ${available.join(', ')}.`
+        : `Target "${target}" is not defined in ${CLI_FILENAME}. Add it with: powersync link cloud --target=${target} --instance-id=<id>`
+    );
+  }
+
+  return { ...link, target };
+}
+
+/** Suggestion for a missing link when cli.yaml defines targets but none was selected. */
+export function suggestTargets(cliConfig: CloudCLIConfig | null): string[] {
+  const names = Object.keys(cliConfig?.targets ?? {});
+  return names.length > 0
+    ? [`Select a target from ${CLI_FILENAME} with --target or POWERSYNC_TARGET: ${names.join(', ')}.`]
+    : [];
+}
diff --git a/packages/schemas/src/CLIConfig.ts b/packages/schemas/src/CLIConfig.ts
index d18ea105..37b35e77 100644
--- a/packages/schemas/src/CLIConfig.ts
+++ b/packages/schemas/src/CLIConfig.ts
@@ -1,9 +1,19 @@
 import * as t from 'ts-codec';
 
+export const CloudTargetConfig = t.object({
+  instance_id: t.string,
+  org_id: t.string.optional(),
+  project_id: t.string.optional()
+});
+
+export type CloudTargetConfig = t.Encoded<typeof CloudTargetConfig>;
+
 export const CloudCLIConfig = t.object({
   instance_id: t.string.optional(),
   org_id: t.string.optional(),
   project_id: t.string.optional(),
+  /** Named targets selected with --target or POWERSYNC_TARGET. The top-level fields stay the default. */
+  targets: t.record(CloudTargetConfig).optional(),
   type: t.literal('cloud')
 });