Docs

Upgrading to Cloud

Migrate from local mode to cloud. Your methodology and context carry forward.

When you are ready to connect a PM tool, unlock the dashboard, or work with a team, upgrading from local to cloud is a single command. Your methodology, context, and knowledge base carry forward. You gain the connected layer without losing anything you have built.

Run the Upgrade

Terminal 
flydocs connect

The upgrade process validates your FlyDocs API key, links the project to a cloud workspace, and refreshes server-managed skill scripts. Account creation and provider connection happen in the portal — sign up there, connect Linear or Jira, generate an API key, then run flydocs connect in your project.

What Happens During Upgrade

  1. API key validation: reads your key from ~/.flydocs/credentials (the global credentials store) and validates it against the relay
  2. Workspace selection: if your account has multiple workspaces, you pick which one this project links to
  3. Config migration: updates .flydocs/config.json from "tier": "local" to "tier": "cloud" and writes the workspace ID
  4. Provider configuration: pulls the workspace's connected PM tool (Linear, Jira) and status mapping from the relay
  5. Refresh skills: prompts you to run flydocs update next to pull the latest server-managed skill scripts for your workspace

Before and after

.flydocs/config.json (before) 
{
  "tier": "local",
  "provider": {
    "type": "local"
  }
}
.flydocs/config.json (after) 
{
  "tier": "cloud",
  "provider": {
    "type": "linear",
    "teamId": "your-team-uuid"
  },
  "workspace": {
    "activeProjects": ["project-uuid"],
    "product": {
      "name": "My Product",
      "labelIds": ["label-uuid"]
    }
  },
  "statusMapping": {
    "BACKLOG": "Backlog",
    "READY": "Todo",
    "IMPLEMENTING": "In Progress",
    "BLOCKED": "On Hold",
    "REVIEW": "Internal Review",
    "TESTING": "QA",
    "COMPLETE": "Done"
  }
}

What Stays the Same

The upgrade changes where issues are stored and how scripts communicate. Everything else is preserved.

  • All skills: workflow methodology, stack patterns, and coding conventions
  • All hooks: 7 hooks across 5 event types, same enforcement behavior
  • Workflow lifecycle: Capture through Close, same stages, same commands
  • Project context: flydocs/context/project.md and knowledge base
  • Knowledge graph: decisions, learnings, and session history
  • Enforcement architecture: stop gates, transition validation, auto-formatting
  • Agent definitions: same sub-agents with the same constraints

What Changes

  • Issues sync with your PM tool: Linear, Jira, or whichever provider you connect
  • Relay API is active: scripts call the relay instead of the local file backend
  • Workspace config applies: team settings, label sync, and shared configuration
  • Dashboard access: the FlyDocs portal for project visibility and management
  • Multi-project support: work across multiple projects in one workspace
  • Team features: shared workspaces, cross-repo context, and service descriptor sync

Local Issues After Upgrade

Existing local issue files remain on disk in your project but become inert once the tier flips to cloud — new operations go to your PM provider, not the local store. New issues created after the upgrade go directly to Linear or Jira through the relay.

Automatic migration of existing local issues to your PM tool is on the post-launch roadmap. For now, if you need a local issue tracked in the cloud, recreate it with /capture after upgrading.

Low-Friction Transition

The upgrade is designed to be non-disruptive. Your methodology and context carry forward completely. You just gain the connected layer: PM integration, the relay API, and team features. There is no re-learning, no reconfiguration of skills or hooks, and no change to how you interact with your AI coding tool.

If you are evaluating FlyDocs, start local. When the methodology proves useful, upgrade to cloud to connect it to your existing tools and team.

Next