Install the FlyDocs CLI: setup walkthrough

Install the FlyDocs CLI to connect your project to your workflow. The CLI pulls configuration from the cloud, detects your stack, and installs everything your AI coding tool needs to work within a structured workflow.

Prerequisites

• Node.js 18.17+
• Python 3.8+ for workflow scripts and automation
• An AI coding tool: Cursor, Claude Code, Warp, Codex, or Windsurf
• A FlyDocs account. Sign up at app.flydocs.ai, or use --tier local for offline evaluation.

Install

Install the CLI globally via npm:

npm install -g @flydocs/cli

Or run without installing:

npx @flydocs/cli init

Initialize your project

Run flydocs init in your project directory:

cd your-project
flydocs init

The init command walks you through setup:

1. API key. Paste the fdk_ key from your portal account. Stored globally at ~/.flydocs/credentials.
2. Workspace selection. Choose which workspace to connect this repo to. The workspace ID is written to .flydocs/config.json and committed to the repo.
3. Artifact pull. Skills, hooks, commands, and cursor rules are downloaded from the server and written to your project directories.
4. Stack detection. Scans your project for frameworks, languages, and tooling (TypeScript, React, Next.js, Python, Go, etc.).
5. Context generation. Creates flydocs/context/project.md with your stack, standards, and project scope, plus flydocs/context/service.json with your service descriptor.

What happens during init

The CLI does three things: pull cloud config, detect your environment, and write project files.

Cloud configuration

The CLI sends your API key and workspace ID to the relay. The relay returns your workspace configuration: provider type, team mapping, status mapping, labels, and custom rules. This config is authoritative and isn't edited locally.

Stack detection

The CLI reads your package.json, tsconfig.json, framework config files, and directory structure to identify your stack. Detected frameworks are written into project.md so your AI agent understands the project from the first prompt.

Artifact installation

Skills, hooks, commands, and tool-specific rules are delivered from the server as managed artifacts. The CLI writes them to the appropriate directories for your AI tools. Each artifact is versioned with a monotonic version number, and every flydocs sync checks for updates.

Directories created

After init, your project has these new directories:

For the full directory layout, see File Structure.

Cloud vs local

The default init path connects to the cloud. Your API key authenticates against the relay, and workspace configuration drives all provider operations.

For offline evaluation or air-gapped environments, pass --tier local:

flydocs init --tier local

Local mode gives you file-based issues, full workflow enforcement, and session context: everything except PM tool integration. You can connect a cloud account later without losing local work. See Local Mode for details.

Multi-repo workspaces

If you run flydocs init in a directory with sibling repos (e.g., a parent directory containing frontend/, backend/, and shared/), the CLI detects this and offers to set up a multi-repo workspace.

This creates .flydocs-workspace.json at the workspace root with a topology index mapping each repo's purpose, stack, and dependencies. Skills and scripts live at the workspace root. Config and context live in each child repo.

See Workspaces & Topology for the full topology model.

Updating

Pull the latest skills and configuration from the server:

flydocs sync

This checks for updated artifacts using the monotonic version number and pulls any changes. Your project context, configuration, and custom settings are preserved.

Update the CLI binary itself:

flydocs self-update

Next

Your First Workflow: walk through a complete development cycle from session start to issue close.