chore: internal docs for beta

README.md

@@ -48,7 +48,8 @@
 
 ## Documentation
 
-For complete documentation, please visit [https://storyblok.com/docs](https://storyblok.com/docs/packages/my-joyful-package)
+> [!WARNING]
+> Official documentation for this package v4 is still in development. In the meantime, please refer to the internal documentation for the [v4 beta](src/README.md).
 
 ## Setup
 

src/README.md

@@ -0,0 +1,59 @@
+![Storyblok ImagoType](https://raw.githubusercontent.com/storyblok/.github/refs/heads/main/profile/public/github-banner.png)
+
+# Storyblok CLI
+
+## Installation
+
+For the latest beta version, install the package using the following command:
+
+```bash
+npm install storyblok@beta
+```
+
+Or for an specific beta version:
+
+```bash
+npm install storyblok@4.0.0-beta.<version>
+```
+
+## API
+
+| Command | Status | Notes |
+|---------|--------|-------|
+| [`login`](./commands/login/README.md) | ✅ | Improved DX and credentials storage in ~/.storyblok/credentials.json |
+| [`logout`](./commands/logout/README.md) | ✅ | |
+| [`user`](./commands/user/README.md) | ✅ | |
+| [`languages pull`](./commands/languages/README.md) | ✅ | Replaces previous pull-languages |
+| [`components pull`](./commands/components/pull/README.md) | ✅ | Replaces previous pull-components |
+| [`components push`](./commands/components/push/README.md) | ✅ | Replaces previous push-components. Also handles dependencies such as groups, tags, presets and whitelists. (Datasources is pending) |
+| `components delete` | 📝 | Will replace delete-component and delete-components |
+| [`migrations generate`](./commands/migrations/generate/README.md) | ✅ | Replaces previous generate-migrations |
+| [`migrations run`](./commands/migrations/run/README.md) | ✅ | Replaces previous run-migrations |
+| [`migrations rollback`](./commands/migrations/rollback/README.md) | ✅ | Replaces previous rollback-migrations |
+| [`types generate`](./commands/types/generate/README.md) | ✅ | Replaces previous generate-typescript-typedefs |
+| `sync` | ⚠️ | |
+| `datasources pull` | 📝 | |
+| `datasources push` | 📝 | |
+| `datasources delete` | 📝 | Will replace delete-datasources |
+| `select` | 💬 | To be discussed |
+| `quickstart` | 💬 | To be discussed |
+| `spaces` | 💬 | To be discussed |
+| `import` | 💬 | To be discussed |
+
+### Status Legend
+- ✅ Ready: Feature is implemented and ready to use
+- 📝 Planned: Feature is planned for future implementation
+- ⚠️ v3: Feature is available only in v3
+- 💬 TBD: Feature is under discussion
+
+## Global Options
+
+These options are available for all commands:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-v, --verbose` | Enable verbose output for debugging | `false` |
+| `--ci` | Enable CI mode (coming soon) | `false` |
+
+> [!TIP]
+> When reporting a bug or opening a support ticket, please run the command with the `--verbose` flag and add the output to it. This will help us better understand and resolve the issue.

src/commands/components/README.md

@@ -0,0 +1,11 @@
+# Components Command
+
+The `components` module provides tools to manage Storyblok components and their dependencies.
+
+## Subcommands
+
+- [`pull`](./pull/README.md): Download components from your Storyblok space.
+- [`push`](./push/README.md): Upload components and their dependencies (groups, tags, presets, whitelists) to your Storyblok space.
+- `delete` (coming soon): Remove components from your Storyblok space.
+
+> See each subcommand for detailed usage, options, and examples.

src/commands/components/pull/README.md

@@ -0,0 +1,190 @@
+# Components Pull Command
+
+The `components pull` command allows you to download components and their dependencies from your Storyblok space.
+
+## Basic Usage
+
+```bash
+storyblok components pull --space YOUR_SPACE_ID
+```
+
+This will download all components and their dependencies to consolidated files:
+```
+.storyblok/
+└── components/
+    └── YOUR_SPACE_ID/
+        ├── components.json      # All components
+        ├── groups.json         # Component groups
+        ├── presets.json        # Component presets
+        └── tags.json           # Component tags
+```
+
+> [!WARNING]
+> The `--filename` option is ignored when using `--separate-files`. Each component will be saved with its own name.
+
+## Pull a Single Component
+
+```bash
+storyblok components pull COMPONENT_NAME --space YOUR_SPACE_ID
+```
+
+This will download a single component and its dependencies to:
+```
+.storyblok/
+└── components/
+    └── YOUR_SPACE_ID/
+        ├── COMPONENT_NAME.json  # Single component
+        ├── groups.json         # Component groups
+        ├── COMPONENT_NAME.presets.json        # Component presets
+        └── tags.json           # Component tags
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-s, --space <space>` | (Required) The ID of the space to pull components from | - |
+| `-f, --filename <filename>` | Custom name for the components file | `components` |
+| `--sf, --separate-files` | Create a separate file for each component | `false` |
+| `--su, --suffix <suffix>` | Suffix to add to the files names  | |
+| `-p, --path <path>` | Custom path to store the files | `.storyblok/components` |
+
+## Examples
+
+1. Pull all components with default settings:
+```bash
+storyblok components pull --space 12345
+```
+Generates:
+```
+.storyblok/
+└── components/
+    └── 12345/
+        ├── components.json      # All components
+        ├── groups.json         # Component groups
+        ├── presets.json        # Component presets
+        └── tags.json           # Component tags
+```
+
+2. Pull a single component:
+```bash
+storyblok components pull hero --space 12345
+```
+Generates:
+```
+.storyblok/
+└── components/
+    └── 12345/
+        ├── hero.json           # Single component
+        ├── groups.json         # Component groups
+        ├── hero.presets.json   # Component presets
+        └── tags.json           # Component tags
+```
+
+3. Pull components with a custom file name:
+```bash
+storyblok components pull --space 12345 --filename my-components
+```
+Generates:
+```
+.storyblok/
+└── components/
+    └── 12345/
+        ├── my-components.json  # All components
+        ├── groups.json         # Component groups
+        ├── presets.json        # Component presets
+        └── tags.json           # Component tags
+```
+
+4. Pull components with custom suffix:
+```bash
+storyblok components pull --space 12345 --suffix dev
+```
+Generates:
+```
+.storyblok/
+└── components/
+    └── 12345/
+        ├── components.dev.json  # All components
+        ├── groups.json         # Component groups
+        ├── presets.json        # Component presets
+        └── tags.json           # Component tags
+```
+
+5. Pull components to separate files:
+```bash
+storyblok components pull --space 12345 --separate-files
+```
+Generates:
+```
+.storyblok/
+└── components/
+    └── 12345/
+        ├── hero.json           # Individual components
+        ├── hero.presets.json   # Component presets
+        ├── feature.json
+        ├── feature.presets.json
+        ├── ...
+        ├── groups.json         # Component groups
+        └── tags.json           # Component tags
+```
+
+6. Pull components to a custom path:
+```bash
+storyblok components pull --space 12345 --path ./backup
+```
+Generates:
+```
+backup/
+└── components/
+    └── 12345/
+        ├── components.json      # All components
+        ├── groups.json         # Component groups
+        ├── presets.json        # Component presets
+        └── tags.json           # Component tags
+```
+
+## File Structure
+
+The command follows this pattern for file generation:
+```
+{path}/
+└── components/
+    └── {spaceId}/
+        ├── {filename}.{suffix}.json  # Components file
+        ├── groups.json              # Component groups
+        ├── presets.json             # Component presets
+        └── tags.json                # Component tags
+```
+
+When using `--separate-files`:
+```
+{path}/
+└── components/
+    └── {spaceId}/
+        ├── {componentName1}.json        # Individual components
+        ├── {componentName1}.presets.json # Component presets
+        ├── {componentName2}.json
+        ├── {componentName2}.presets.json
+        ├── ...
+        ├── groups.json                  # Component groups
+        └── tags.json                    # Component tags
+```
+
+Where:
+- `{path}` is the base path (default: `.storyblok`)
+- `{spaceId}` is your Storyblok Space ID
+- `{filename}` is the name you specified (default: `components`)
+- `{suffix}` is the suffix you specified (default: space ID)
+- `{componentName}` is the name of the component
+
+## Notes
+
+- The space ID is required
+- The command will create the necessary directories if they don't exist
+- When using `--separate-files` or single component, presets are saved in separate files named `{componentName}.presets.json`
+- The command downloads:
+  - Components
+  - Component groups
+  - Component presets
+  - Component tags

src/commands/components/pull/index.ts

@@ -14,7 +14,7 @@ const program = getProgram();
 componentsCommand
   .command('pull [componentName]')
   .option('-f, --filename <filename>', 'custom name to be used in file(s) name instead of space id')
-  .option('--sf, --separate-files [value]', 'Argument to create a single file for each component')
+  .option('--sf, --separate-files', 'Argument to create a single file for each component')
   .option('--su, --suffix <suffix>', 'suffix to add to the file name (e.g. components.<suffix>.json)')
   .description(`Download your space's components schema as json. Optionally specify a component name to pull a single component.`)
   .action(async (componentName: string | undefined, options: PullComponentsOptions) => {