사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/storyblok/agent-plugin --skill storyblok-use-cli시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
Work with Storyblok through the CLI
Running it
Resolve the binary once: node_modules/.bin/storyblok, else the package manager's exec (pnpm exec, npx), else a global storyblok. A one-off in a project that does not depend on it can run through pnpm dlx storyblok or npx -y storyblok — no install needed.
Most commands work against one space. Set it once in storyblok.config.ts (space) and every command picks it up; otherwise pass --space <id> on each. Offline commands — schema validate among them — take no space at all.
Space-to-space is the exception: push and migrations run read their local files from --from <id> when it is given, and from --space otherwise.
Prefer flags over prompts: every unset option a command needs becomes an interactive question you cannot answer. Add --verbose when a command fails.
Region
Never ask for it. Every command runs against the region of the active session — STORYBLOK_REGION, or ~/.storyblok/credentials.json, falling back to eu — and neither --region nor the config file can retarget it.
Check when a command answers HTTP 404 ["This record could not be found"]: a wrong region says that, and so do a wrong space id and a deleted space, naming no region either way. storyblok user ends with … on <region> region; compare it with the region the space id encodes.
| Space id | Region |
|---|---|
≥ 2⁴⁸ (281474976710656) | bits 48–52: 0/1 → eu, 2 → us, 3 → ca, 4 → ap, 6 → cn |
| < 1000000 | eu (legacy cn shares this range) |
| < 2000000 | us |
| < 3000000 | ca |
| < 4000000 | ap |
On a mismatch, stop and hand it to the user: storyblok logout then storyblok login into that region, or STORYBLOK_REGION=<region> with a token from it. Never attempt the login and never ask for a token.
--region only carries where there is no session to override it: storyblok create --token <token> --region <region> writes the region into the generated project.
Auth
storyblok user reports the session. When it reports one, every command is already authenticated and there is nothing for you to do.
With no session, ask the user to run storyblok login themselves; it is a chain of interactive prompts ending in a password, an OTP or a pasted token, so you cannot complete it. Re-check afterwards.
Schema as code
The only way to manage a space's schema from the repo. Definitions come from @storyblok/schema; storyblok-model-content owns how to write them.
| Command | Does |
|---|---|
schema init --space <id> --out-dir src/schema | One-time bootstrap of TypeScript definitions from a space. Refuses a non-empty directory. |
schema validate <entry-file> | Static check — offline, no login, no space. Run it before every push. |
schema push <entry-file> --space <id> --dry-run | The diff. Always this before the real push. |
schema push <entry-file> --space <id> | Apply. Scaffolds migrations for breaking changes (--no-migrations to skip) and writes component JSON (--no-write-components). |
schema rollback [changeset-file] --space <id> | Undo a push from its changeset. |
Everything else
| Command | For |
|---|---|
stories pull/push, stories validate | Bulk story content as local files |
components pull/push | Component schemas as local JSON, including space-to-space |
datasources pull/push/delete | Datasources and their entries |
assets pull/push, assets transfer | Bulk assets; transfer moves them between spaces |
migrations generate/run/rollback | Transform content in existing stories after a schema change |
types generate | TypeScript definitions from a space's components. Not in schema-as-code mode — types come from Schema<typeof schema> there. |
create [project-path] | Scaffold a new project from an official template |
There is no stories delete, and no delete for components outside schema push --delete. Where the CLI has no command for the job, take the next best available approach.
How a push maps ids
stories push treats the ids in local files as placeholders and maps them onto the space, so hand-written files push as well as pulled ones. What has to be right is how they refer to each other.
- Every file needs an
idand auuid. For a new story, invent both — any
value unique within the push (1001, author-maya) does.
- A reference in the content of a story — a multilink's
id, a richtext story
link's or an internal_stories option's uuid — takes the local value when its target is in the same push and the remote one when it is not.
parent_idis the exception: it only ever resolves against the push
itself.** A parent_id that names no file in this push — the folder's real id in the space included — is dropped, and the story is created at the root and reported as succeeded.
- So to add stories to a folder that already exists,
stories pullit first:
the folder's own file joins the push, is matched to the existing folder rather than duplicated, and its local id is what the children point at.
- Spell
full_slugout as the full path (authors/maya) — it is what orders
creation, so a parent is created before the stories that name it.
- Pull the components first: with no
.storyblok/components/<space>/, the push
aborts.
published: truein a file publishes that story;--publishpublishes
everything in the push.
- A failed story does not fail the push. Read the totals rather than the exit
code, and read the placement back from the space.
Adding stories to a folder that already exists
components pull, thenstories pull.- Leave in
.storyblok/stories/<space>/only the folder's own file and the new
files you write; move the rest aside. Every file in that directory is pushed, and a push rewrites each story from its local copy — so a file you did not mean to touch is a remote edit you did not mean to revert.
- Name each new file
<slug>_<uuid>.json, matching the uuid inside it. That is
what a pull writes and what --cleanup unlinks; any other name makes the push report a failure for a story it created perfectly well.
- Say what this will change (see Before a write), dry-run, then push with
--cleanup. It deletes the local files the push contained — local files only, nothing in the space — so no invented id is left to collide with what a later pull writes under the real one.
- Read back where the new stories landed — a story created at the root is
reported as succeeded. stories pull shows it, but it refetches every story in the space; skip it when something cheaper has already answered the question.
Leave .storyblok/stories/<space>/manifest.jsonl alone. It records which story each local id created, and that is what makes a second push of the same files an update instead of a second copy. Keep it and invented ids stay safe to re-push; delete it, or renumber the local ids, and the next push duplicates everything.
Files
.storyblok/ holds what the CLI pulls and pushes — components/, stories/, datasources/, migrations/. storyblok.config.ts sets defaults through defineConfig from storyblok/config. Code-driven schema definitions are project source and live in the source root (src/schema/), not here.
Before a write
State what will change before the first write of the task, and run --dry-run wherever it exists — with the same flags as the real run, or the preview is of a different command.
A dry run prints what a real run prints — the same per-story lines, the same succeeded totals — behind a warning at the top saying nothing was written. For stories push nothing reaches the API at all: the ids it echoes back are your local ones, no parent is resolved against the space.
Destructive — each needs its own explicit confirmation naming what is lost, and never runs unattended:
schema push --delete— deletes remote components and datasources absent from
the local schema.
migrations run— rewrites content in existing stories. Dry-run and read the
diff first.
stories push,components push— overwrite remote entities with local
files, so a stale local copy silently reverts remote edits.
datasources delete.
Report what changed from the command's own output.
Beyond this page
storyblok <command> --help outranks this file whenever they disagree.
Each command has its own reference page, named after the command with a hyphen: stories push is <https://www.storyblok.com/docs/tooling/cli/stories-push.md>. Fetch that page for a command's complete flag list. When no single command's page answers the question, the index, <https://www.storyblok.com/docs/tooling/cli.md>, lists every page, including setup (storyblok.config.ts) and global-options.