사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/next-space/buildin-skill --skill buildin-cli시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
Buildin CLI
Use the Buildin CLI (buildin) for Buildin V2 API work: pages, blocks, databases, search, Markdown content, and files.
Carry out the user-authorized operation through the installed CLI; do not stop at describing commands when execution is requested. For native database fields, read the operation recipe before preparing request files. It covers schema, record relations, formula reads and verification.
The CLI source repository may be private. Do not ask the user to clone source code before using the CLI. Install or update the released binary from the official Buildin CDN only after the user explicitly approves it.
Use only the Buildin command, Buildin base URL, BUILDIN_* environment variables, and Buildin credential store for Buildin work.
Mandatory preflight
Complete this preflight before a remote Buildin API call. CLI help, endpoint documentation, and offline planning do not require authentication.
- Inspect whether the CLI is available without installing or updating it:
if command -v buildin >/dev/null 2>&1; then
buildin version
else
echo "Buildin CLI is not installed"
fiIf the CLI is missing or outdated, explain that the official installer is available at https://cdn.buildin.ai/buildin-cli/install (or https://cdn.buildin.ai/buildin-cli/install.ps1 on Windows). Do not download, execute, or update it until the user explicitly approves that action.
After approval, use only the official URL and a user-approved version. Download an installer to a temporary file; show its source, version, and SHA-256 hash; and compare it with an official checksum or signature before execution. If no official integrity data is available, stop and offer manual installation rather than executing an unverified installer. Remove temporary installer files after the attempt.
- If the CLI is installed, inspect authentication and active identity:
buildin --json doctor
buildin --json whoamiContinue only when the checks show authenticated Buildin credentials. If authentication is missing or invalid, do not start a login flow automatically. Explain the available options and wait for the user's explicit choice:
- If
BUILDIN_TOKENis already set, rerunbuildin --json doctorand
buildin --json whoami; do not ask for another login.
- Browser login:
buildin login --browser. - Manual setup for headless environments:
buildin --json login --manual. - Configure
BUILDIN_TOKENor saved credentials through an approved secret
channel.
Do not run plain buildin login in agent sessions because it can block on an interactive method prompt. Do not make API calls or draw conclusions from incomplete data until authentication is verified. After the user explicitly approves a login method, run only that selected method and then rerun buildin --json doctor and buildin --json whoami.
Use this browser login command only after the user explicitly selects browser login:
buildin login --browserUse manual setup only after the user explicitly selects it for a headless or remote environment:
buildin --json login --manualIf a command is missing or help output looks stale, explain that buildin update can update the CLI and wait for explicit user approval before running it.
Useful install overrides:
BUILDIN_INSTALL_DIR- install directory.BUILDIN_VERSION- exact release version, such asv0.1.10.BUILDIN_CLI_RELEASE_BASE_URL- alternate release base URL for tests.
First rule: ask the CLI
The CLI is self-documenting. Prefer these commands over guessing syntax or request fields:
buildin --help- list global options and top-level commands.buildin help <command...>- show usage, options, examples, and notes for any
command or subcommand.
buildin api ls- list public API endpoints and request field hints.buildin api ls --plain- compact endpoint list for scanning.buildin api --docs <PATH> -X <METHOD>- show agent-readable Markdown docs
for one endpoint, including parameters, examples, and safety notes.
buildin api --spec <PATH> -X <METHOD>- show the exact embedded OpenAPI
fragment for one endpoint.
buildin --json doctor- inspect local authentication and configuration
state when auth or base URL selection is unclear.
buildin --json whoami- verify the active Buildin identity.buildin markdown get <page-id>- retrieve page content as Markdown.
If you are unsure about syntax, request body fields, pagination, auth source, or command coverage, run help first.
Credentials and configuration
The CLI resolves credentials in this precedence order:
--token <token>BUILDIN_TOKEN- saved login credentials in the Buildin credential store
This is CLI resolution behavior, not authorization to expose a credential. Do not pass --token in agent commands, logs, or shared shells: it can leak via process listings or shell history. Do not ask users to paste bearer tokens into chat. Use preconfigured BUILDIN_TOKEN, saved credentials, or an approved secret channel; redact any credential that appears in command output.
If no credential is configured, offer browser login, manual setup, or an approved secret path and wait for the user to select one. After the selected login succeeds, rerun buildin --json doctor and buildin --json whoami.
OAuth refresh and sandbox permissions
A saved browser-OAuth credential may require write access to the credential store even for a read-only API command, because the CLI rotates and atomically persists tokens before sending the API request.
- If
error.codeiscredential_store_permission_deniedor
needsCredentialWritePermission is true, do not start login. Request narrowly scoped write access to the directory containing credentialsPath, then rerun buildin --json doctor and the original command. Reauthentication cannot fix a local filesystem denial.
- If the error code is
oauth_refresh_failedoroauth_refresh_rejectedand
reauthorizationRequired is false, retry the same command later; do not start login.
- Offer login only when
reauthorizationRequiredorrefreshTokenExpiredis
true, or OAuth explicitly reports that the refresh token is invalid, expired, or revoked.
- Older CLI versions may report only
Operation not permittedor OS error 1.
With stored, refreshable OAuth credentials, treat this as probable credential-store sandbox denial and inspect the reported path and sandbox before assuming the token is revoked.
Never copy credentials.json into the workspace or expose its contents.
Common environment variables:
BUILDIN_TOKEN- bearer token for API calls.BUILDIN_BASE_URL- API base URL; default ishttps://api.buildin.ai.BUILDIN_CONFIG_DIR- config directory; default follows the Buildin profile.BUILDIN_USER_AGENT- custom user agent suffix.
Do not print bearer tokens, write them into files, or paste them into request bodies. Do not call the Buildin V2 API with curl; use the CLI so auth, product defaults, retries, and error formatting stay consistent.
Working rules
- Use
--jsonfor stable machine-readable stdout. Requireok:trueand
read the API object under data (created IDs are data.id). For ok:false, inspect error; do not treat a failed command as a completed operation.
- Keep JSON request bodies in local files and pass them with
--body <file>. - Keep Markdown replacement content in local files and pass it with
--file <file>. - Prefer domain commands over
api call;buildin api --docsnames a
recommended domain command when one exists.
- For paginated commands, inspect JSON output for cursors and repeat with the
command's cursor option.
Write safety
Before any remote create, update, append, upload, replace, or raw API write:
- Verify the exact target, operation, and expected impact (including record
count, affected blocks, or uploaded files).
- Read the current target first when feasible. For a Markdown replacement,
compare the existing content unless the user explicitly authorized a full replacement. Use --if-match when the CLI exposes a version or ETag.
- The user\'s task authorizes its requested changes. Resolve IDs from reads or
creation results and choose routine implementation details within that scope; do not require the user to supply generated IDs or repeat an existing approval. Ask only when targets remain ambiguous or the change exceeds the request.
- Confirm files and external URLs are user-authorized and do not contain
credentials or private data not intended for the target workspace.
The CLI intentionally rejects DELETE API calls. This Skill does not execute or suggest bypasses; use a dedicated deletion workflow with a second confirmation.
Memory templates
For travel, journal or reading memory tables, use the template recipe. It includes three ready-to-create schemas and append-only agent usage rules.
Common workflows
Read a page
buildin --json page get <page_id>
buildin markdown get <page_id> > page.mdUse Markdown for page content work whenever possible. It is easier to inspect, edit, and diff than raw block JSON.
Replace page Markdown
buildin markdown put --file page.md <page_id>Only run this after confirming the target page ID and replacement file.
Create or update a page with JSON
Create a local JSON body file, then pass it to the CLI:
buildin --json page create --body page.json
buildin --json page update --body patch.json <page_id>For idempotent creates, use --idempotency-key <key>.
Blocks and children
For callout/toggle first-line edits, blank placeholders or moving a title out of a child paragraph, read Own text and children. callout.rich_text is the callout first editable line; toggle.rich_text is the folding title. children are independent blocks. Read both the block itself and its children; Markdown alone cannot establish equivalent layout.
buildin --json block get <block_id>
buildin --json block children <block_id>
buildin --json block append <block_id> --body children.json
buildin --json block update <block_id> --body block-patch.jsonDatabases
buildin --json database get <database_id>
buildin --json database query <database_id> --body query.json
buildin --json database create --body database.json
buildin --json database update <database_id> --body patch.json
buildin --json page property get <page_id> <property_id>Use buildin api --docs or command help to inspect filter and sort body shapes before writing query.json.
Search
buildin --json search text "roadmap" --page-size 10
buildin --json search semantic "tasks about quarterly planning" --space-id <space_id> --page-size 10Use text search for exact titles, keywords, and known phrases. Use semantic search when intent matters more than exact wording.
Files
Upload a local file for a parent page:
buildin --json file upload --parent-page <page_id> ./report.pdfAppend a Buildin-hosted file block with the returned object name and size:
buildin --json block append-file <block_id> --oss-name <oss_name> --size <bytes>Append an external file URL:
buildin --json block append-file <block_id> --external-url https://example.com/report.pdfFallback API calls
Use api call only when no domain command covers the endpoint. Lookup sequence:
buildin api ls --plain
buildin api --docs /v2/blocks/{block_id}/children -X PATCH
buildin api --spec /v2/blocks/{block_id}/children -X PATCH
buildin --json api call PATCH /v2/blocks/:block_id/children --param block_id=<block_id> --body body.jsonFor POST, PUT, or PATCH, read --docs and --spec first and apply the write-safety rules above. --param fills path placeholders first; remaining keys become query parameters. Use --header NAME=VALUE only for non-secret headers such as If-Match; never put credentials or sessions in headers.
Troubleshooting
- Command not found: offer the official installer at
https://cdn.buildin.ai/buildin-cli/installand wait for explicit approval before using it. - Unknown command or option: ask approval before running
buildin update, then runbuildin <command> --help. - Authentication failure: run
buildin --json doctor, then follow the OAuth
refresh and sandbox-permission rules above. Do not equate every failure or HTTP 401 with an expired refresh token.
- Unexpected API shape: run
buildin api --docs <PATH> -X <METHOD>and
buildin api --spec <PATH> -X <METHOD> before retrying.