Adding assets:list: List assets with optional search filter via Management API

Author: roberto-butti

.claude/commands/blokctl-api.md

@@ -47,6 +47,7 @@ Every CLI command is backed by a reusable Action class with no CLI dependencies:
 | `Story\StoriesTagsAssignAction` | Assign tags to stories | `->tagged`, `->errors` |
 | `Story\StoryVersionsAction` | List story versions | `->versions`, `->storyId`, `->count()` |
 | `Story\StoriesWorkflowAssignAction` | Assign stage to unstaged stories (preflight+execute) | `->countWithoutStage`, `->workflowStages` |
+| `Asset\AssetsListAction` | List/search assets (MAPI only) | `->assets`, `->count()` |
 | `Asset\AssetsUnreferencedAction` | Find unreferenced assets | `->unreferencedAssets`, `->totalAssets`, `->referencedCount`, `->storiesAnalyzed` |
 | `Workflow\WorkflowsListAction` | List workflows+stages | `->workflows`, `->count()` |
 | `Workflow\WorkflowStageShowAction` | Show stage details | `->stage`, `->workflowName` |

.claude/commands/blokctl-cli.md

@@ -49,6 +49,7 @@ Use this skill when the user wants to run blokctl commands to manage a Storyblok
 
 ### Assets
 
+- **`assets:list`** — List assets. Options: `--search`, `--page` (`-p`), `--per-page` (max 1000). Management API only, no preview token needed.
 - **`assets:unreferenced`** — Detect orphaned assets not referenced in any story. Fetches all assets via Management API (1000/page), scans all stories via CDN API (higher rate limits), then diffs.
 
 ### Workflows

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 All notable changes to `blokctl` will be documented in this file.
 
+## 0.6.1 - 2026-04-03
+- Adding `assets:list`: List assets with optional search filter via Management API
+
 ## 0.6.0 - 2026-04-03
 - Upgrading `symfony/console` from ^7.0 to ^8.0
 - Upgrading `phpunit/phpunit` from ^12.0 to ^13.0

README.md

@@ -683,6 +683,22 @@ Displays stage details: name, ID, workflow, position, color, publish permissions
 
 ### Assets
 
+#### `assets:list` — List assets
+
+```bash
+php bin/blokctl assets:list -S 290817118944379
+php bin/blokctl assets:list -S 290817118944379 --search=hero
+php bin/blokctl assets:list -S 290817118944379 --per-page=100 --page=2
+```
+
+| Option | Short | Description |
+|---|---|---|
+| `--search` | | Search assets by filename |
+| `--page` | `-p` | Page number (default: 1) |
+| `--per-page` | | Results per page (max 1000, default: 25) |
+
+Lists assets via the Management API. Each asset displays its filename, ID, content type, file size, and creation date. No preview token needed.
+
 #### `assets:unreferenced` — List assets not referenced in any story
 
 ```bash
@@ -1277,6 +1293,24 @@ $result->workflowId;   // int
 
 ### Assets
 
+#### List assets
+
+```php
+use Blokctl\Action\Asset\AssetsListAction;
+
+$result = (new AssetsListAction($client))->execute(
+    spaceId: $spaceId,
+    search: 'hero',
+    page: 1,
+    perPage: 25,
+);
+
+$result->assets; // Assets collection
+$result->count(); // int
+```
+
+Uses the Management API only. No preview token needed.
+
 #### Find unreferenced assets
 
 ```php

bin/blokctl

@@ -2,6 +2,7 @@
 <?php
 require __DIR__ . "/../vendor/autoload.php";
 
+use Blokctl\Command\AssetsListCommand;
 use Blokctl\Command\AssetsUnreferencedCommand;
 use Blokctl\Command\AppProvisionInstallCommand;
 use Blokctl\Command\AppProvisionListCommand;
@@ -37,6 +38,7 @@ $dotenv->safeLoad();
 
 $application = new Application("blokctl", "1.0.0-dev");
 
+$application->addCommand(new AssetsListCommand());
 $application->addCommand(new AssetsUnreferencedCommand());
 $application->addCommand(new AppProvisionInstallCommand());
 $application->addCommand(new AppProvisionListCommand());

src/Action/Asset/AssetsListAction.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blokctl\Action\Asset;
+
+use Storyblok\ManagementApi\Endpoints\AssetApi;
+use Storyblok\ManagementApi\ManagementApiClient;
+use Storyblok\ManagementApi\QueryParameters\AssetsParams;
+use Storyblok\ManagementApi\QueryParameters\PaginationParams;
+
+final readonly class AssetsListAction
+{
+    public function __construct(
+        private ManagementApiClient $client,
+    ) {}
+
+    public function execute(
+        string $spaceId,
+        ?string $search = null,
+        int $page = 1,
+        int $perPage = 25,
+    ): AssetsListResult {
+        $params = new AssetsParams(
+            search: $search,
+        );
+
+        $pagination = new PaginationParams(
+            page: $page,
+            perPage: $perPage,
+        );
+
+        $assets = (new AssetApi($this->client, $spaceId))
+            ->page($params, $pagination)->data();
+
+        return new AssetsListResult(
+            assets: $assets,
+        );
+    }
+}

src/Action/Asset/AssetsListResult.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blokctl\Action\Asset;
+
+use Storyblok\ManagementApi\Data\Assets;
+
+final readonly class AssetsListResult
+{
+    public function __construct(
+        public Assets $assets,
+    ) {}
+
+    public function count(): int
+    {
+        return $this->assets->count();
+    }
+}

src/Command/AssetsListCommand.php

@@ -0,0 +1,121 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blokctl\Command;
+
+use Blokctl\Action\Asset\AssetsListAction;
+use Blokctl\Render;
+use Storyblok\ManagementApi\Data\Asset;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+#[AsCommand(
+    name: 'assets:list',
+    description: 'List assets with optional search filter',
+)]
+class AssetsListCommand extends AbstractCommand
+{
+    #[\Override]
+    protected function configure(): void
+    {
+        parent::configure();
+        $this
+            ->addOption(
+                'search',
+                null,
+                InputOption::VALUE_REQUIRED,
+                'Search assets by filename',
+            )
+            ->addOption(
+                'page',
+                'p',
+                InputOption::VALUE_REQUIRED,
+                'Page number',
+                '1',
+            )
+            ->addOption(
+                'per-page',
+                null,
+                InputOption::VALUE_REQUIRED,
+                'Results per page (max 1000)',
+                '25',
+            );
+    }
+
+    protected function execute(
+        InputInterface $input,
+        OutputInterface $output,
+    ): int {
+        /** @var string|null $search */
+        $search = $input->getOption('search');
+        /** @var string $pageOption */
+        $pageOption = $input->getOption('page');
+        /** @var string $perPageOption */
+        $perPageOption = $input->getOption('per-page');
+
+        try {
+            $result = (new AssetsListAction($this->client))->execute(
+                spaceId: $this->spaceId,
+                search: $search,
+                page: (int) $pageOption,
+                perPage: (int) $perPageOption,
+            );
+        } catch (\RuntimeException $runtimeException) {
+            Render::error($runtimeException->getMessage());
+            return self::FAILURE;
+        }
+
+        if ($result->count() === 0) {
+            Render::log('No assets found');
+            return self::SUCCESS;
+        }
+
+        Render::titleSection(
+            'Assets (page ' . $pageOption .
+            ', showing ' . $result->count() . ')',
+        );
+
+        /** @var Asset $asset */
+        foreach ($result->assets as $asset) {
+            $details = [];
+            $details[] = 'id: ' . $asset->id();
+            $contentType = $asset->contentType();
+            if ($contentType !== '') {
+                $details[] = $contentType;
+            }
+
+            $size = $asset->contentLength();
+            if ($size !== null && $size > 0) {
+                $details[] = $this->formatBytes($size);
+            }
+
+            $createdAt = $asset->createdAt();
+            if ($createdAt !== null && $createdAt !== '') {
+                $details[] = $createdAt;
+            }
+
+            Render::labelValue(
+                $asset->filename(),
+                implode(' | ', $details),
+            );
+        }
+
+        return self::SUCCESS;
+    }
+
+    private function formatBytes(int $bytes): string
+    {
+        if ($bytes < 1024) {
+            return $bytes . ' B';
+        }
+
+        if ($bytes < 1048576) {
+            return round($bytes / 1024, 1) . ' KB';
+        }
+
+        return round($bytes / 1048576, 1) . ' MB';
+    }
+}