CLI

Use @01.software/cli when an operator or coding agent can run shell commands. Human CLI commands are interactive and operator-facing. The 01 agent namespace is a separate JSON protocol for coding agents; do not mix their output or exit contracts.

Choose A CLI SurfaceCopy Anchor Link

Install the public package with the package manager used for your shell environment, then inspect the shipped help:

npm install --global @01.software/cli
01 --help
01 agent --help

Human operators can run 01 login and 01 tenant use <name>. Automated agents should prefer SOFTWARE_PUBLISHABLE_KEY plus SOFTWARE_SECRET_KEY from trusted environment storage. Never put a real token in command arguments, source files, logs, or chat.

For app --connect, enter a new authenticator TOTP in the browser approval when operator MFA enforcement is active and the account is enrolled or required. Recovery codes can restore login but cannot approve the app grant. No new CLI flag is needed; the signed grant and existing exchange remain compatible.

Credential Rotation After Operator MFA ActivationCopy Anchor Link

Servers do not send a rotation-deadline header, so the CLI shows no rotation warning. When operator MFA is activated, PATs owned by a super-admin and API keys with super-admin scope that were not issued from an MFA-verified session stop working at once with the existing 401 key_invalid. Run 01 login again, complete operator MFA, and replace credentials saved in scripts, CI and MCP clients. Updating the CLI does not activate MFA enforcement.

Configure An Embedded Admin AppCopy Anchor Link

Workspace admins use the Human CLI to manage the active workspace's single embedded app binding. This control-plane action requires the user PAT obtained by 01 login; workspace API keys (sk01_) are rejected.

The explicit role opt-in example below shows --allowed-roles with published CLI 0.21.0. This version is the example's reference release, not a first or minimum supported version. See Embedded Admin for receiver opt-in.

01 tenant use acme
01 embedded-app configure \
  --label "Operations" \
  --origin https://admin.example.com \
  --path /workspace \
  --dry-run
01 embedded-app configure \
  --label "Operations" \
  --origin https://admin.example.com \
  --path /workspace
# Explicit execution-role opt-in (receiver opt-in is also required)
01 embedded-app configure --label Operations --origin https://admin.example.com --allowed-roles tenant-admin tenant-viewer
01 embedded-app show
01 embedded-app disable

--dry-run validates locally and performs no write. The origin must be one exact HTTPS origin and the path must be relative without a query or fragment. These commands are operator-facing and are not part of the 01 agent machine-stable manifest.

Use --actions-file actions.json to configure up to 20 stable collection actions. Each entry has id, label, collection, and boolean requiresSelection. Omit the option to preserve existing actions; an empty array clears them. Old strict servers reject unsupported action fields. Download-policy omission has its separate false default, so preserving actions does not preserve a previously enabled download setting. Add --allow-downloads to configure only when this binding needs iframe file downloads. The default is false; every full configure without the option resets false on a server supporting downloads, including older CLI requests after a prior opt-in. The CLI omits allowDownloads from the request when the option is absent; --allow-downloads explicitly sends true and --no-allow-downloads sends false. show and configure readback include allowDownloads. An older strict server rejects a configure body containing this field, so update the server before using either download option. File encryption and password handling belong to the app; this option does not enforce them or recall files already received.

Without --allowed-roles, configure preserves the stored role policy, including an empty or viewer-only allowlist. Only a new unset policy defaults to tenant-admin. Explicit roles replace the policy; successful output reports the stored roles. A local dry run without the option omits roles from its patch.

Set Admin Panel Field VisibilityCopy Anchor Link

A secret key with write scope, or a tenant-admin personal access token, can show only the fields your app uses in the active workspace's Admin Panel. List the configurable paths first, preview the change with --dry-run, then run the same command without it:

01 field-config list links
01 field-config set links --visible platform,expiresAt --dry-run
01 field-config set links --visible platform,expiresAt

--visible takes the paths to keep visible; every other configurable path in that collection is hidden. Output lists the paths that become hidden (hide) and visible (show). An unknown path fails before any write, and an unchanged selection writes nothing. The collection's own menu visibility is preserved. A collection whose feature is off still lists its fields, but saving fails until the feature is enabled. Field visibility applies to the Admin Panel only: stored values and API read and write access are unchanged. These commands are not part of the 01 agent manifest.

Diagnose A Local App IntegrationCopy Anchor Link

Run the redacted diagnostic from an app directory after configuring its SDK environment:

01 doctor
01 doctor --app-env-file .env.local
01 doctor --origin https://app.example.com
01 --format json doctor
01 --format ndjson doctor

01 doctor defaults to localized human output; explicit json and ndjson formats are for machine consumers. For Next.js/CRA it reads .env, .env.development, .env.local, then .env.development.local; for Vite it reads .env, .env.local, .env.development, then .env.development.local. Other apps use only .env then .env.local, or one explicit regular --app-env-file. It validates one app publishable/secret pair, resolves the SDK API target from those files only, and probes SDK tenant context. It never falls back to CLI PAT credentials, prints a credential value or raw response body, mutates state, or runs project scripts. --origin performs an uncredentialed CORS OPTIONS diagnostic and does not send Authorization or a secret. The origin must be an absolute http(s) URL. A 403 is denied even when it carries ACAO; successful responses need matching ACAO. 404, 408, 429, 5xx, and network failures are inconclusive rather than a CORS conclusion.

01 agent doctor returns exactly one JSON value. A completed diagnostic exits with Agent success (0) even when its payload reports blocked or attention; an invalid explicit app-env-file or origin is Agent INVALID_INPUT (exit 2).

Diagnose Payment ConfigurationCopy Anchor Link

01 payment diagnose
01 --format json payment diagnose --expected-environment live
01 agent payment diagnose --market <market-uuid> --expected-environment test --pretty

Use the normal CLI credential resolver with a matching publishable key and PAT. The PAT must resolve current tenant-admin membership on its server-pinned tenant with the ecommerce entitlement. App sk01_, PK-only, customer, and lower-role credentials are denied; no client tenant selector is accepted.

The read-only result separates managed Toss/PortOne and custom market configuration coverage. It reports none/single/multiple candidates, the selected environment, readiness-pin reasons, configuration and stored-secret presence booleans, and optional expected-environment comparisons. Candidate cardinality is checked before single-candidate provider configuration/secret requirements. An unbound legacy environment is a fact, not proof of live readiness. No account list, MID, client key, secret, ciphertext, customer, or money is returned. Stored-secret presence only reports that a value is stored; confirm decryption, key validity, provider authorization, and payment success with a test payment in the provider environment. Custom or free checkout can still work when managed configuration is incomplete. This command skips the saved-secret decryption check, so a stored secret this deployment cannot decrypt is still reported as present; check saved-secret readability in the connection panel or workspace diagnostics. For PortOne, configured means at least one profile (Hosted or Standard V2) can be requested explicitly with its current settings; request that profile and test each payment method you offer. Currency support follows new payment session rules: Toss and PortOne Standard V2 charge KRW, and Hosted charges the market's ISO currency. Console payment readiness checks connections without currencies, so the two results can differ. Custom coverage follows checkout settings, so a custom provider without a currency list reads as configured; add its currencies before creating custom payment sessions. Inactive markets are excluded from results and coverage; --market reports one as not found. Reason codes are additive, so unknown codes are preserved as-is.

Human output is localized by default; explicit json and ndjson are machine formats. Agent output is exactly one JSON value and is advertised by discovery.payment.diagnose in manifest version 1. A completed observation exits 0 even for unready or expected-environment mismatch facts; input/auth/query failures use the existing namespace errors and exit codes. No plan/confirm, idempotency key, provider call, attestation, or mutation is performed.

Discover The Agent ContractCopy Anchor Link

Start every Agent CLI integration with the manifest instead of scraping help text:

01 agent manifest --pretty
01 agent context --counts --pretty
01 agent schema articles --pretty

The version 1 manifest lists the current server-auth collections and their supported operations. context reports the active workspace, features, active collections, and field configuration. schema returns the workspace-effective field contract. Schema writable metadata is advisory; server access control and the manifest's reviewed plan operations remain authoritative.

context checks credentials and workspace reachability, not deployment readiness. It may complete pending initial workspace provisioning, so do not run it where no state change is allowed. Never pass a secret as a command-line argument.

For customers and products, schema may also return optional collection.customFields with storagePath: "customData". Each active definition contains its machine key and type, optional required: true, and select option storage values. Display labels, help text, internal ids, and workspace metadata are omitted. This structural discovery does not grant access to stored customData values or add write operations.

Query And GetCopy Anchor Link

All manifest collections support query and get. Keep agent context small with filters, pagination, sorting, and field selection:

01 agent query articles \
  --where '{"status":{"equals":"published"}}' \
  --limit 10 \
  --sort=-updatedAt \
  --select=id,title,updatedAt

01 agent get articles art_123 --select=id,title,updatedAt --pretty

query returns the paginated Payload shape; get returns one bare document. --limit and --page accept positive decimal integers only.

Plan And Confirm Content ChangesCopy Anchor Link

Agent writes are deliberately two-step. plan validates input and stores an expiring local plan without changing remote data. Review its JSON, then run the returned confirmCommand with the exact token and hash:

printf '%s\n' '{"title":"Release notes","status":"draft"}' | \
  01 agent plan create articles --data-stdin --pretty

01 agent confirm <planToken> --hash <planHash> --pretty

Mutation payloads are accepted through --data-stdin or --data-file only. The manifest currently advertises create/update/delete plans for articles and article categories/tags, links and link categories/tags, plus canvases, canvas-categories, and canvas-tags. documents, document-categories, and document-types advertise create/update but not delete. The canvas-node-types and canvas-edge-types catalogs remain read-only through the Agent CLI. Do not infer write support from schema fields.

Plans expire after 15 minutes by default, bind to the current auth/API context, and reject stale update/delete targets. If the remote mutation fails, the plan returns to pending so the caller can retry confirm with the same token and hash while the plan is valid. After the mutation succeeds, the claimed or consumed plan must not be replayed. Human CLI --dry-run is a different operator workflow, not the Agent plan contract.

Product Detail And CommerceCopy Anchor Link

The Agent namespace provides a shaped product read in addition to generic collection reads:

01 agent product detail \
  --slug canvas-bag \
  --market kr \
  --locale en \
  --fallback-locale ko \
  --pretty

Use exactly one of --slug or --id. Unavailable products return a successful discriminated result such as {"found":false,"reason":"not_published"}.

The Agent namespace does not currently provide commerce mutation commands. Use the existing Human CLI domain commands shown by 01 order --help, 01 cart --help, 01 checkout --help, 01 payment-session --help, and related groups when an operator-facing command fits; use the server SDK for application or automated commerce mutations. Do not treat Human CLI text/output or exit codes as the Agent JSON contract.

Cart capability operations, Checkout creation, and PaymentSession creation/cancellation/confirmation accept sensitive JSON only through --data-stdin or --data-file. Interactive stdin is rejected, and each input is limited to 1 MiB. Successful --dry-run output confirms only the action and validity; it never echoes payload values. This keeps Cart/Checkout capabilities, customer snapshots, idempotency keys, and provider authorization material out of shell history, process listings, and logs. Keep input files access-restricted and remove them after use. 01 cart create is the exception: it accepts no input and uses canonical defaults because the request contains no capability; use a sensitive input source only when supplying optional market or attributes.

Output, Errors, And RetriesCopy Anchor Link

Agent success and normal errors each emit exactly one JSON value on stdout. Add --pretty for two-space-indented success JSON. Add --output-file <path> to write the complete success result to a secure file and receive a compact stdout receipt containing outputFile and bytes:

01 agent query articles --limit 100 --output-file ./articles.json

On POSIX, the result file uses mode 0600; unsafe targets such as symlinks, directories, and multiply linked files are rejected.

Normal error envelopes include error.code, error.message, and error.retryable. Retry only when retryable is true, honor retryAfter when present, and preserve operation idempotency.

The CLI does not automatically rerun commands based on retryable. Read commands may already have gone through automatic SDK retries before returning an error. Validation, auth, not-found, plan, and monthly quota errors are terminal; network/timeouts, HTTP 503, transient rate limits, and explicitly unavailable providers may be retryable.

Published package baselineCopy Anchor Link

These command examples target the published @01.software/cli@0.20.1 package; the explicit role opt-in example uses CLI 0.21.0 as its reference release.

Check 01 --version for your installed CLI version, its help for available commands, and 01 agent manifest for machine-readable operations.

Use Build Options for the create 0.2.10 / init 0.19.4 / SDK 0.74.0 setup tuple; choose the CLI version separately. Real workspace operations still require the appropriate credentials and runtime deployment.

For the browser/server embedded session protocol after CLI configuration, use Embedded Admin.

Next ActionsCopy Anchor Link

• Need credential boundaries: open Authentication & Keys.
• Need typed application code or commerce mutations: open SDK.
• Need a direct HTTP escape hatch: open API.
• Need hosted, shell-less discovery: open MCP.