Adding workflows:list: List workflows and their stages (lookup stage IDs by name)

Author: roberto-butti

CHANGELOG.md

@@ -3,8 +3,9 @@
 All notable changes to `blokctl` will be documented in this file.
 
 ## 0.2.2 - WIP
+- Adding `workflows:list`: List workflows and their stages (lookup stage IDs by name)
 - Adding `story:workflow-change`: Change the workflow stage of a story
-- 
+
 ## 0.2.1 - 2026-03-14
 -  Adding`story:move` — Move a story to a different folder
 

README.md

@@ -363,6 +363,16 @@ php bin/blokctl stories:workflow-assign -S 290817118944379 --workflow-stage-id=1
 
 Finds all stories without a workflow stage and assigns the selected stage to them.
 
+### Workflows
+
+#### `workflows:list` — List workflows and their stages
+
+```bash
+php bin/blokctl workflows:list -S 290817118944379
+```
+
+Lists all workflows configured in the space, along with their stages and IDs. Useful for looking up stage IDs by name (e.g. before using `story:workflow-change --stage-id=...`).
+
 ### Components
 
 #### `components:list` — List components with filters
@@ -755,6 +765,25 @@ if ($result->countWithoutStage > 0) {
 }
 ```
 
+### Workflows
+
+#### List workflows and stages
+
+```php
+use Blokctl\Action\Workflow\WorkflowsListAction;
+
+$result = (new WorkflowsListAction($client))->execute($spaceId);
+
+$result->workflows; // array of ['id' => int, 'name' => string, 'isDefault' => bool, 'stages' => [...]]
+$result->count();   // int
+
+foreach ($result->workflows as $workflow) {
+    foreach ($workflow['stages'] as $stage) {
+        // $stage['id'], $stage['name'], $stage['position']
+    }
+}
+```
+
 ### Components
 
 #### List components

bin/blokctl

@@ -23,6 +23,7 @@ use Blokctl\Command\StoryMoveCommand;
 use Blokctl\Command\StoryShowCommand;
 use Blokctl\Command\StoryWorkflowChangeCommand;
 use Blokctl\Command\UserMeCommand;
+use Blokctl\Command\WorkflowsListCommand;
 use Symfony\Component\Console\Application;
 
 $dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/..');
@@ -50,5 +51,6 @@ $application->add(new StoryMoveCommand());
 $application->add(new StoryShowCommand());
 $application->add(new StoryWorkflowChangeCommand());
 $application->add(new UserMeCommand());
+$application->add(new WorkflowsListCommand());
 
 $application->run();

src/Action/Workflow/WorkflowsListAction.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blokctl\Action\Workflow;
+
+use Storyblok\ManagementApi\Endpoints\WorkflowApi;
+use Storyblok\ManagementApi\Endpoints\WorkflowStageApi;
+use Storyblok\ManagementApi\ManagementApiClient;
+
+final readonly class WorkflowsListAction
+{
+    public function __construct(
+        private ManagementApiClient $client,
+    ) {}
+
+    public function execute(string $spaceId): WorkflowsListResult
+    {
+        $workflowApi = new WorkflowApi($this->client, $spaceId);
+        $workflows = $workflowApi->list()->data();
+
+        $stageApi = new WorkflowStageApi($this->client, $spaceId);
+
+        /** @var array<int, array{id: int, name: string, isDefault: bool, stages: array<int, array{id: int, name: string, position: int}>}> $items */
+        $items = [];
+
+        /** @phpstan-ignore foreach.nonIterable */
+        foreach ($workflows as $workflow) {
+            /** @var int $workflowId */
+            $workflowId = $workflow->get('id');
+            /** @var string $workflowName */
+            $workflowName = $workflow->get('name');
+            $isDefault = $workflow->getBoolean('is_default');
+
+            $stages = $stageApi->list((string) $workflowId)->data();
+
+            /** @var array<int, array{id: int, name: string, position: int}> $stageItems */
+            $stageItems = [];
+
+            /** @phpstan-ignore foreach.nonIterable */
+            foreach ($stages as $stage) {
+                /** @var int $stageId */
+                $stageId = $stage->get('id');
+                /** @var string $stageName */
+                $stageName = $stage->get('name');
+                /** @var int $position */
+                $position = $stage->get('position');
+                $stageItems[] = [
+                    'id' => $stageId,
+                    'name' => $stageName,
+                    'position' => $position,
+                ];
+            }
+
+            $items[] = [
+                'id' => $workflowId,
+                'name' => $workflowName,
+                'isDefault' => $isDefault,
+                'stages' => $stageItems,
+            ];
+        }
+
+        return new WorkflowsListResult(workflows: $items);
+    }
+}

src/Action/Workflow/WorkflowsListResult.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blokctl\Action\Workflow;
+
+final readonly class WorkflowsListResult
+{
+    /**
+     * @param array<int, array{id: int, name: string, isDefault: bool, stages: array<int, array{id: int, name: string, position: int}>}> $workflows
+     */
+    public function __construct(
+        public array $workflows,
+    ) {}
+
+    public function count(): int
+    {
+        return count($this->workflows);
+    }
+}

src/Command/WorkflowsListCommand.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blokctl\Command;
+
+use Blokctl\Action\Workflow\WorkflowsListAction;
+use Blokctl\Render;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+#[AsCommand(
+    name: 'workflows:list',
+    description: 'List workflows and their stages',
+)]
+class WorkflowsListCommand extends AbstractCommand
+{
+    protected function execute(
+        InputInterface $input,
+        OutputInterface $output,
+    ): int {
+        $result = (new WorkflowsListAction($this->client))->execute($this->spaceId);
+
+        if ($result->count() === 0) {
+            Render::log('No workflows found');
+            return self::SUCCESS;
+        }
+
+        foreach ($result->workflows as $workflow) {
+            $label = $workflow['name'];
+            if ($workflow['isDefault']) {
+                $label .= ' (default)';
+            }
+
+            Render::titleSection($label . ' — ID: ' . $workflow['id']);
+
+            foreach ($workflow['stages'] as $stage) {
+                Render::labelValue(
+                    $stage['name'],
+                    'ID: ' . $stage['id'],
+                );
+            }
+        }
+
+        return self::SUCCESS;
+    }
+}

tests/Unit/Action/Workflow/WorkflowsListActionTest.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Action\Workflow;
+
+use Blokctl\Action\Workflow\WorkflowsListAction;
+use PHPUnit\Framework\Attributes\Test;
+use Tests\TestCase;
+
+final class WorkflowsListActionTest extends TestCase
+{
+    #[Test]
+    public function execute_returns_workflows_with_stages(): void
+    {
+        $client = $this->createMockClient(
+            $this->mockResponse('list-workflows'),        // WorkflowApi->list
+            $this->mockResponse('list-workflow-stages'),   // WorkflowStageApi->list (1st workflow)
+            $this->mockResponse('list-workflow-stages'),   // WorkflowStageApi->list (2nd workflow)
+        );
+
+        $action = new WorkflowsListAction($client);
+        $result = $action->execute('680');
+
+        $this->assertSame(2, $result->count());
+
+        // First workflow
+        $this->assertSame(12345, $result->workflows[0]['id']);
+        $this->assertSame('Article ', $result->workflows[0]['name']);
+        $this->assertFalse($result->workflows[0]['isDefault']);
+        $this->assertCount(2, $result->workflows[0]['stages']);
+        $this->assertSame(653554, $result->workflows[0]['stages'][0]['id']);
+        $this->assertSame('Drafting', $result->workflows[0]['stages'][0]['name']);
+        $this->assertSame(653555, $result->workflows[0]['stages'][1]['id']);
+        $this->assertSame('Review', $result->workflows[0]['stages'][1]['name']);
+
+        // Second workflow (default)
+        $this->assertSame(12346, $result->workflows[1]['id']);
+        $this->assertSame('Default one', $result->workflows[1]['name']);
+        $this->assertTrue($result->workflows[1]['isDefault']);
+    }
+
+    #[Test]
+    public function execute_returns_empty_when_no_workflows(): void
+    {
+        $emptyJson = json_encode(['workflows' => []], JSON_THROW_ON_ERROR);
+
+        $client = $this->createMockClient(
+            new \Symfony\Component\HttpClient\Response\MockResponse(
+                $emptyJson,
+                ['http_code' => 200],
+            ),
+        );
+
+        $action = new WorkflowsListAction($client);
+        $result = $action->execute('680');
+
+        $this->assertSame(0, $result->count());
+        $this->assertSame([], $result->workflows);
+    }
+}