Adding folder:create: Create a folder (with optional parent folder by slug or ID)

Author: roberto-butti

CHANGELOG.md

@@ -2,7 +2,8 @@
 
 All notable changes to `blokctl` will be documented in this file.
 
-## 0.2.2 - WIP
+## 0.3.0 - 2026-03-17
+- Adding `folder:create`: Create a folder (with optional parent folder by slug or ID)
 - Adding `workflow:stage-show`: Show details of a workflow stage by name or ID
 - Adding `workflows:list`: List workflows and their stages (lookup stage IDs by name)
 - Adding `story:workflow-change`: Change the workflow stage of a story

README.md

@@ -188,6 +188,35 @@ php bin/blokctl space:preview-add -S 290817118944379 'Staging' 'https://staging.
 | Argument | `name` | **(required)** Environment name (e.g. `Staging`, `Local Development`) |
 | Argument | `url` | **(required)** Environment URL |
 
+### Folders
+
+#### `folder:create` — Create a folder
+
+```bash
+# Create a folder at root
+php bin/blokctl folder:create -S 290817118944379 'Archive'
+
+# Create a folder inside a parent folder (by slug)
+php bin/blokctl folder:create -S 290817118944379 'Old Posts' --parent-slug=articles
+
+# Create a folder inside a parent folder (by ID)
+php bin/blokctl folder:create -S 290817118944379 'Old Posts' --parent-id=123456
+
+# Interactive: prompts for folder name
+php bin/blokctl folder:create -S 290817118944379
+```
+
+| Type | Name | Description |
+|---|---|---|
+| Argument | `name` | Folder name (prompted interactively if omitted) |
+
+**Parent folder options** (optional, mutually exclusive — defaults to root):
+
+| Option | Description |
+|---|---|
+| `--parent-slug` | Parent folder slug (e.g. `articles`, `articles/archive`) |
+| `--parent-id` | Parent folder numeric ID (default: `0` for root) |
+
 ### Stories
 
 #### `stories:list` — List stories with filters
@@ -668,6 +697,29 @@ $result = $action->preflight($spaceId);
 $action->execute($spaceId, $result, 'Staging', 'https://staging.example.com/?path=');
 ```
 
+### Folders
+
+#### Create a folder
+
+```php
+use Blokctl\Action\Folder\FolderCreateAction;
+
+$action = new FolderCreateAction($client);
+
+// Create at root
+$result = $action->execute($spaceId, 'Archive');
+
+// Create inside a parent folder (by ID)
+$result = $action->execute($spaceId, 'Old Posts', parentId: 123456);
+
+// Resolve parent folder by slug, then create
+$parentId = $action->resolveParentBySlug($spaceId, 'articles');
+$result = $action->execute($spaceId, 'Old Posts', parentId: $parentId);
+
+$result->folder;    // Story object (the created folder)
+$result->parentId;  // int (0 for root)
+```
+
 ### Stories
 
 #### List stories with filters

bin/blokctl

@@ -10,6 +10,7 @@ use Blokctl\Command\SpacePreviewListCommand;
 use Blokctl\Command\SpacePreviewSetCommand;
 use Blokctl\Command\SpacePreviewAddCommand;
 use Blokctl\Command\SpaceDeleteCommand;
+use Blokctl\Command\FolderCreateCommand;
 use Blokctl\Command\SpaceDemoRemoveCommand;
 use Blokctl\Command\SpacesListCommand;
 use Blokctl\Command\StoriesWorkflowAssignCommand;
@@ -34,6 +35,7 @@ $application = new Application('blokctl', '1.0.0');
 
 $application->add(new AppProvisionInstallCommand());
 $application->add(new AppProvisionListCommand());
+$application->add(new FolderCreateCommand());
 $application->add(new SpaceInfoCommand());
 $application->add(new SpacePreviewListCommand());
 $application->add(new SpacePreviewSetCommand());

src/Action/Folder/FolderCreateAction.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blokctl\Action\Folder;
+
+use Storyblok\ManagementApi\Data\Story;
+use Storyblok\ManagementApi\Data\StoryComponent;
+use Storyblok\ManagementApi\Endpoints\StoryApi;
+use Storyblok\ManagementApi\ManagementApiClient;
+use Storyblok\ManagementApi\QueryParameters\StoriesParams;
+
+final readonly class FolderCreateAction
+{
+    public function __construct(
+        private ManagementApiClient $client,
+    ) {}
+
+    /**
+     * Resolve a parent folder ID from its slug.
+     *
+     * @throws \RuntimeException if the folder is not found
+     */
+    public function resolveParentBySlug(
+        string $spaceId,
+        string $folderSlug,
+    ): int {
+        $params = new StoriesParams(folderOnly: true, withSlug: $folderSlug);
+        $folders = (new StoryApi($this->client, $spaceId))->page($params)->data();
+
+        if (count($folders) !== 1) {
+            throw new \RuntimeException(
+                'Parent folder not found with slug: ' . $folderSlug,
+            );
+        }
+
+        /** @var array{id: int} $folder */
+        $folder = $folders[0];
+
+        return (int) $folder['id'];
+    }
+
+    /**
+     * Create a folder.
+     *
+     * @throws \RuntimeException if the creation fails
+     */
+    public function execute(
+        string $spaceId,
+        string $name,
+        int $parentId = 0,
+    ): FolderCreateResult {
+        $storyApi = new StoryApi($this->client, $spaceId);
+
+        $folder = new Story($name, $this->slugify($name), new StoryComponent('folder'));
+        $folder->set('is_folder', true);
+
+        if ($parentId > 0) {
+            $folder->setFolderId($parentId);
+        }
+
+        $response = $storyApi->create($folder);
+
+        if (!$response->isOk()) {
+            throw new \RuntimeException(
+                'Failed to create folder: ' . $response->getErrorMessage(),
+            );
+        }
+
+        return new FolderCreateResult(
+            folder: $response->data(),
+            parentId: $parentId,
+        );
+    }
+
+    private function slugify(string $name): string
+    {
+        $slug = mb_strtolower($name);
+        $slug = (string) preg_replace('/[^a-z0-9\s-]/', '', $slug);
+        $slug = (string) preg_replace('/[\s-]+/', '-', $slug);
+
+        return trim($slug, '-');
+    }
+}

src/Action/Folder/FolderCreateResult.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blokctl\Action\Folder;
+
+use Storyblok\ManagementApi\Data\Story;
+
+final readonly class FolderCreateResult
+{
+    public function __construct(
+        public Story $folder,
+        public int $parentId,
+    ) {}
+}

src/Command/FolderCreateCommand.php

@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blokctl\Command;
+
+use Blokctl\Action\Folder\FolderCreateAction;
+use Blokctl\Render;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+use function Laravel\Prompts\text;
+
+#[AsCommand(
+    name: 'folder:create',
+    description: 'Create a folder',
+)]
+class FolderCreateCommand extends AbstractCommand
+{
+    #[\Override]
+    protected function configure(): void
+    {
+        parent::configure();
+        $this
+            ->addArgument('name', InputArgument::OPTIONAL, 'Folder name')
+            ->addOption('parent-slug', null, InputOption::VALUE_REQUIRED, 'Parent folder slug (e.g. articles/archive)')
+            ->addOption('parent-id', null, InputOption::VALUE_REQUIRED, 'Parent folder numeric ID (default: 0 for root)');
+    }
+
+    protected function execute(
+        InputInterface $input,
+        OutputInterface $output,
+    ): int {
+        /** @var string|null $name */
+        $name = $input->getArgument('name');
+        /** @var string|null $parentSlug */
+        $parentSlug = $input->getOption('parent-slug');
+        /** @var string|null $parentIdRaw */
+        $parentIdRaw = $input->getOption('parent-id');
+
+        if ($parentSlug && $parentIdRaw) {
+            $output->writeln('<error>Provide only one of --parent-slug or --parent-id</error>');
+            return self::FAILURE;
+        }
+
+        if (empty($name) && !$input->getOption('no-interaction')) {
+            $name = text(
+                label: 'Enter the folder name',
+                placeholder: 'E.g. Articles, Archive',
+                required: true,
+            );
+        }
+
+        if (empty($name)) {
+            $output->writeln('<error>Folder name is required</error>');
+            return self::FAILURE;
+        }
+
+        $action = new FolderCreateAction($this->client);
+
+        try {
+            // Resolve parent folder
+            $parentId = 0;
+            if ($parentSlug !== null) {
+                $parentId = $action->resolveParentBySlug($this->spaceId, $parentSlug);
+            } elseif ($parentIdRaw !== null) {
+                $parentId = (int) $parentIdRaw;
+            }
+
+            $result = $action->execute($this->spaceId, $name, $parentId);
+        } catch (\RuntimeException $runtimeException) {
+            Render::error($runtimeException->getMessage());
+            return self::FAILURE;
+        }
+
+        Render::title('Folder Created');
+        Render::labelValue('Name', $result->folder->name());
+        Render::labelValue('Slug', $result->folder->slug());
+        Render::labelValue('ID', $result->folder->id());
+        if ($result->parentId > 0) {
+            Render::labelValue('Parent folder ID', (string) $result->parentId);
+        } else {
+            Render::labelValue('Parent', 'Root');
+        }
+
+        return self::SUCCESS;
+    }
+}

tests/Fixtures/one-folder-created.json

@@ -0,0 +1,38 @@
+{
+    "story": {
+        "name": "Archive",
+        "parent_id": 0,
+        "group_id": null,
+        "alternates": [],
+        "created_at": "2026-03-17T10:00:00.000Z",
+        "deleted_at": null,
+        "sort_by_date": null,
+        "tag_list": [],
+        "updated_at": "2026-03-17T10:00:00.000Z",
+        "published_at": null,
+        "id": 550001,
+        "uuid": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
+        "is_folder": true,
+        "content": {
+            "_uid": "a1b2c3d4-e5f6-7890-abcd-000000000001",
+            "component": "folder"
+        },
+        "published": false,
+        "slug": "archive",
+        "path": null,
+        "full_slug": "archive",
+        "default_root": null,
+        "disable_fe_editor": false,
+        "parent": null,
+        "is_startpage": false,
+        "unpublished_changes": false,
+        "meta_data": null,
+        "imported_at": null,
+        "pinned": false,
+        "breadcrumbs": [],
+        "position": 0,
+        "stage": null,
+        "release_id": null,
+        "lang": "default"
+    }
+}