# CLI

셸에서 문서를 읽고 써요. 에이전트와 스크립트용.

## 연결

```sh
export AGENT_CMS_URL=https://app.example.com/api/cms AGENT_CMS_KEY=sgk_…
npx @mainsoft/agent-cms collections
```

`--env <파일>`을 주면 `AGENT_CMS_URL`과 `AGENT_CMS_KEY`를 파일에서 읽어요.

이 명령들은 HTTP로 앱에 접속하므로 어느 폴더에서나 돌아가요. 패키지가 설치되지 않은 곳에서는 `npx`가 받아 와요. 명령에 스코프를 꼭 넣으세요(`bunx @mainsoft/agent-cms …`, `pnpm dlx @mainsoft/agent-cms …`도 똑같아요). `@mainsoft/`를 뺀 `agent-cms`는 npm에 있는 다른 프로젝트의 패키지라서 `could not determine executable to run` 오류로 멈춰요.

## 명령

```sh
npx @mainsoft/agent-cms search "설치 테이블" --collections docs
npx @mainsoft/agent-cms get posts hello-world --draft
npx @mainsoft/agent-cms put posts ./hello-world.md --publish --note "launch post"
npx @mainsoft/agent-cms patch posts hello-world ./ops.json --expected-version 3 --dry-run
npx @mainsoft/agent-cms call archive_document '{"collection":"posts","slug":"old","archived":true}'
```

`put`은 문서를 만들어요. 이미 있는 문서를 고치려면 읽은 버전을 `--expected-version N`으로 넘기세요. 그사이 누가 저장했으면 덮어쓰지 않고 충돌로 실패해요. `--force`는 이 검사를 건너뛰어요.

## 파일 형식

앞부분(frontmatter)이 있는 마크다운이에요. `slug`, `title`, `summary`, `category`, `keywords`가 아닌 키는 `fields`로 들어가요.

```md
---
title: Hello, world
summary: Our first post
category: News
tags: [launch]
---
Body in **markdown**.
```

## 내보내기, 가져오기, OpenAPI

0.13.0부터.

```sh
npx @mainsoft/agent-cms export ./content --drafts --with-files
npx @mainsoft/agent-cms import ./content --dry-run --diff
npx @mainsoft/agent-cms import ./wordpress.xml --from wordpress --collection posts
npx @mainsoft/agent-cms put guide ./guide
npx @mainsoft/agent-cms openapi > openapi.json
```

`export`는 문서마다 마크다운 파일 하나를 쓰고, `import`는 그것을 초안으로 다시 읽으며 `--dry-run`으로 무엇을 할지 먼저 알려 줍니다. `--from json|csv|wordpress`는 다른 곳의 콘텐츠를 읽습니다. [내보내기와 가져오기](/docs/import-export)를 보세요. `openapi`는 키가 읽을 수 있는 범위의 REST API를 OpenAPI 3.1 문서로 출력합니다.

## 로컬 명령

`init`, `doctor`, `migrate check | print | apply`, `add`는 서버 없이 프로젝트에서 돌아가요. [설치](/docs/install)와 [어드민 화면](/docs/admin-screens)을 보세요.
