Skip to content

[Sync] Named connections with --tag for disambiguating multiple connections per platform #122

@siddharth-bhansali

Description

@siddharth-bhansali

Context

Sync profiles today pin to a connection in one of two ways:

  1. Hardcoded connectionKey (legacy) — "connectionKey": "live::gmail::default::abc123". Breaks silently when the user re-auths and a new key is generated.

  2. Late-bound connection ref (v1.41.0) — "connection": { "platform": "gmail" }. Resolves at runtime, but fails when the user has multiple connections for the same platform:

    Multiple "gmail" connections found. Add a "tag" field to disambiguate.
    

There's no clean way to wire a profile to a specific connection among several on the same platform without falling back to the stale connectionKey approach.

Proposed pattern: named connections

  1. Tag connections at creation time:

    one add gmail --tag personal
    one add gmail --tag work
  2. Sync profiles reference by platform + tag:

    {
      "connection": { "platform": "gmail", "tag": "personal" }
    }
  3. If only one connection exists for a platform, tag stays optional (current behavior).

  4. one add gmail --tag personal on an existing tagged connection refreshes it in place rather than creating a duplicate.

What this eliminates

  • Stale connection keys in profiles after re-auth
  • Duplicate connections from one add on an existing platform
  • The need for external resolvers (several users have built wrapper scripts for this)
  • Ambiguity when multiple connections exist for the same platform

Scope

  • one add <platform> --tag <name> — create or refresh a tagged connection
  • one connection list — show tag column
  • connection: { platform, tag } — recognized in sync profile schema
  • Documentation updates: guide sync, skills/one/SKILL.md, README

Raised in knowledge repo issue withoneai/knowledge#69 — breaking out here since it's CLI-scoped.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions