Standardization of CLI Documentation & Migration Guide (w3 → storacha)

[Keerthivasan-Venkitajalam]

Type

Documentation / Developer Experience

Severity

Medium — User friction and onboarding inconsistency

---

Background

The migration from web3.storage to storacha.network has resulted in a fragmented documentation landscape. While branding has been updated, technical references to the legacy w3 CLI persist across search results and deep-linked tutorials.

Currently, the w3 CLI and @storacha/cli use different namespace configurations and profiles. This creates confusion when users follow mixed-era documentation.

---

Problem Statement

A new user following the current Quickstart installs @storacha/cli.
They then navigate to specific tutorials (for example, "Managing Spaces") that reference legacy commands such as:

w3 space ls

This leads to one of two failure modes:

1. Command not found, if w3 CLI is not installed.
2. Empty or missing space lists, if w3 CLI is installed but the space was created under the storacha profile.

This inconsistency creates cognitive dissonance, increases support load, and risks user churn during onboarding.

---

Proposed Solution

1. Documentation Audit

Perform a repository-wide audit:

• Grep src/pages for instances of w3 (with trailing space)
• Identify and catalog all legacy CLI references

2. Command Standardization

Replace all legacy w3 CLI references with storacha equivalents.

Examples:

• w3 space ls → storacha space ls
• w3 up → storacha up

3. Migration Guide

Add a dedicated Migration Guide page detailing:

• CLI installation differences
• Profile and config path changes
• Authentication and keychain differences
• Common migration pitfalls

4. Global Migration Banner

Add a lightweight alert banner across docs indicating:

• Legacy w3 CLI commands have been superseded
• Link to the Migration Guide

5. Troubleshooting Updates

Extend the Troubleshooting section to cover:

• "Missing Profile" errors
• Empty space listings
• Incorrect CLI installation issues

---

Command Mapping Matrix

Legacy Command (w3)	Modern Command (storacha)	Functional Difference
w3 login	storacha login	Different config file and profile location
w3 space create	storacha space create	Creates DID in a different keychain context
w3 up	storacha up	Same functionality, different auth source
w3 proof add	storacha proof add	Same UCAN logic, different profile context

---

Expected Outcome

• Elimination of outdated CLI references
• Consistent onboarding experience
• Reduced user confusion and support overhead
• Clear migration path for existing w3 CLI users

---

Additional Notes

This documentation update directly improves developer experience and reduces friction for new adopters transitioning from legacy tooling. I am happy to contribute to the audit and migration guide if the maintainers approve the direction.