Five-minute quickstart

Inspect, preview, initialize, and validate an ordinary folder without moving its files.

This workflow turns an existing folder into a Folderbase. Inspection and dry-run steps are read-only.

Building with JSON and Markdown, deploying an app, or connecting multiple people and devices? Choose your use case to see what is available today and what is planned. This quickstart covers the local file foundation.

Prefer a graphical workflow? See the complete Folderbase App journey, including what works in the current native alpha and what remains a product preview.

1. Inspect the folder

npx @folderbase/cli inspect /path/to/project --json

Inspection reports boundaries and metadata without changing the target.

2. Preview initialization

npx @folderbase/cli init /path/to/project --dry-run --json

Review the proposed additions. Initialization is additive: existing files remain in place.

The JSON response includes a stable plan_digest. Keep its digest value so the apply step is bound to the exact folder state and initialization plan you reviewed.

3. Initialize

npx @folderbase/cli init /path/to/project \
  --expected-plan-digest DIGEST_FROM_DRY_RUN \
  --json

Native protocol 0.5 initialization creates only .folderbase/manifest.json by default. Existing files stay where they are. --agent-adapters explicitly adds AGENTS.md and CLAUDE.md; a selected template may add its own reviewed artifacts. FOLDERBASE.md and the user-owned .folderbaseignore remain optional and are never implicit root authority.

4. Validate

npx @folderbase/cli validate /path/to/project --json

Validation checks the Folderbase protocol surface and returns machine-readable diagnostics.

5. See what agents can access

npx @folderbase/cli workspace list /path/to/project --json

The workspace view includes ordinary files while excluding protocol state, repository internals, and reconstructable dependency trees from agent context.

Make the first useful read and save

Follow Operate Folderbase from an agent to read an existing text file and save with the returned content hash as a precondition. If another write changes the bytes, read the current file and reconcile your draft. Node.js apps can use the TypeScript adapter.

Current queries cover file metadata. Application schemas and queries such as “tasks where status is open” belong to the planned record API; they are not installed by this quickstart.

When the folder is disorganized

Do not manually initialize multiple accidental boundaries. Normal Organize and Reorganize are same-root, review-first operations: an agent may analyze the folder and ask consequential questions, but only an explicitly approved, digest-bound plan may change the live root.

Core 0.7.2 does not yet publish the stable process adapter for that App journey. Its experimental migration workflow is a separately named copy-first tool for imports, organized copies, cross-boundary adoption, or splits. Its JSON is not part of CLI JSON v1 and it must not be presented as normal in-place organization.