This is the full developer documentation for Craftybase CLI # Craftybase CLI > Manage your Craftybase inventory from the terminal. Built for humans and agents. ## Install [Section titled “Install”](#install) ```sh curl -fsSL https://cli.craftybase.dev/install | bash ``` With Homebrew: ```sh brew install craftybase/tap/craftybase ``` With Go: ```sh go install github.com/craftybase/craftybase-cli/cmd/craftybase@latest ``` Human-friendly Readable tables, color, and branded help out of the box. Agent-friendly `--json` and `--ndjson` for pipelines, scripts, and tools. Authenticate once `craftybase auth login`, then your token is stored locally. # Page not found > That page doesn't exist. That page doesn’t exist. Head to [Getting Started](/getting-started/) or the [command reference](/reference/craftybase/). # Using with Agents & LLMs > Point models at the docs and use machine-readable output. ## Feed the docs to a model [Section titled “Feed the docs to a model”](#feed-the-docs-to-a-model) The full documentation is available as plain text for LLM context: * **Index:** [`/llms.txt`](/llms.txt) — a curated map of every page. * **Full text:** [`/llms-full.txt`](/llms-full.txt) — all docs concatenated. Any page is also available as raw markdown by appending `.md` to its URL. ## Machine-readable command output [Section titled “Machine-readable command output”](#machine-readable-command-output) Prefer `--json` (one envelope) or `--ndjson` (one object per line, auto-paginated) when an agent consumes CLI output: ```sh craftybase materials list --json craftybase materials list --ndjson ``` Exit codes are stable: `0` success, `3` auth error, `4` not found, `1` otherwise. # Authentication > How the Craftybase CLI resolves and stores your API token. ## Logging in [Section titled “Logging in”](#logging-in) ```sh craftybase auth login # interactive prompt (hidden input) echo "$KEY" | craftybase auth login # from stdin (CI) craftybase auth login --token "$KEY" # explicit flag ``` On success your account name + token are stored in `~/.craftybase/config.toml` (mode `0600`). ## Status & logout [Section titled “Status & logout”](#status--logout) ```sh craftybase auth status # shows account, masked key, and API URL craftybase auth logout # removes stored credentials ``` ## Token resolution precedence [Section titled “Token resolution precedence”](#token-resolution-precedence) The token is resolved in this order — first match wins: 1. `--token` flag 2. `CRAFTYBASE_API_TOKEN` environment variable 3. stored profile (`~/.craftybase/config.toml`) A missing token yields a clear error and exit code `3`. # Configuration > The config file, profiles, and the API URL. ## Config file [Section titled “Config file”](#config-file) Credentials live in `~/.craftybase/config.toml`, keyed by profile (`profiles.default`), written atomically with `0600` permissions. ## API URL [Section titled “API URL”](#api-url) The API base URL is resolved as: `--api-url` flag → `CRAFTYBASE_API_URL` env → stored profile → default (`https://api.craftybase.com`). ## Global flags [Section titled “Global flags”](#global-flags) | Flag | Purpose | | ----------------- | -------------------------------------------------- | | `--json` | Raw API envelope (pretty-printed) | | `--ndjson` | Auto-paginated NDJSON stream | | `--no-color` | Disable ANSI color | | `--token ` | Override stored credentials | | `--api-url ` | Override the API base URL | | `--verbose` | Show HTTP request/response detail (token redacted) | # Getting Started > Install the Craftybase CLI, authenticate, and run your first command. ## Install [Section titled “Install”](#install) ```sh curl -fsSL https://cli.craftybase.dev/install | bash ``` This downloads the right binary for your OS/architecture, verifies its checksum, and installs `craftybase` to `/usr/local/bin` (or `~/.local/bin`). Homebrew (`brew install craftybase/tap/craftybase`) and `go install github.com/craftybase/craftybase-cli/cmd/craftybase@latest` also work. ## Authenticate [Section titled “Authenticate”](#authenticate) ```sh craftybase auth login ``` Paste your Craftybase API key when prompted (input is hidden). Credentials are saved to `~/.craftybase/config.toml`. See [Authentication](/authentication/). ## First command [Section titled “First command”](#first-command) ```sh craftybase materials list ``` Add `--json` for the raw API envelope or `--ndjson` to stream every page. See [Output Formats](/output-formats/). # Output Formats > Tables for humans, JSON and NDJSON for machines. By default, list/show commands print an aligned, colored table. ## JSON [Section titled “JSON”](#json) ```sh craftybase materials list --json ``` Prints the full API envelope (pretty-printed). Pipe into `jq`: ```sh craftybase materials list --json | jq '.materials[] | {id, name}' ``` ## NDJSON (streaming, auto-paginated) [Section titled “NDJSON (streaming, auto-paginated)”](#ndjson-streaming-auto-paginated) ```sh craftybase materials list --ndjson ``` Emits one JSON object per line across all pages — ideal for pipelines. `--json` and `--ndjson` are mutually exclusive. ## Color [Section titled “Color”](#color) Color is on for interactive terminals and off when piped. Disable explicitly with `--no-color` or the `NO_COLOR` environment variable. # Pagination > Fetching one page, all pages, or a stream. List commands are paginated. ```sh craftybase materials list # first page (default size) craftybase materials list --page 2 # a specific page craftybase materials list --all # fetch every page into one table craftybase materials list --ndjson # stream every page as NDJSON ``` `--all` is mutually exclusive with both `--ndjson` and `--page`. Both `--all` and `--ndjson` walk pages automatically using the response `meta.total_pages`. # craftybase > Reference for the craftybase command. ## craftybase [Section titled “craftybase”](#craftybase) Official CLI for the Craftybase Public API ### Synopsis [Section titled “Synopsis”](#synopsis) craftybase is a command-line interface for the Craftybase Public API. Authenticate once, then manage your inventory from the terminal. Documentation: ```plaintext craftybase [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) -h, --help help for craftybase --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase account](/reference/craftybase_account/) - Show account information * [craftybase api](/reference/craftybase_api/) - Make authenticated API requests * [craftybase auth](/reference/craftybase_auth/) - Manage authentication credentials * [craftybase completion](/reference/craftybase_completion/) - Generate shell completion scripts * [craftybase components](/reference/craftybase_components/) - Manage components * [craftybase materials](/reference/craftybase_materials/) - Manage materials * [craftybase products](/reference/craftybase_products/) - Manage products * [craftybase version](/reference/craftybase_version/) - Print version information # craftybase account > Reference for the craftybase account command. ## craftybase account [Section titled “craftybase account”](#craftybase-account) Show account information ### Synopsis [Section titled “Synopsis”](#synopsis) Display account details including name, currency, time zone, and plan. ```plaintext craftybase account [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for account ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase](/reference/craftybase/) - Official CLI for the Craftybase Public API # craftybase api > Reference for the craftybase api command. ## craftybase api [Section titled “craftybase api”](#craftybase-api) Make authenticated API requests ### Synopsis [Section titled “Synopsis”](#synopsis) Make authenticated requests to the Craftybase API. The path must be the full API path starting with /api/v1/. Examples: craftybase api GET /api/v1/account craftybase api GET /api/v1/materials craftybase api GET “/api/v1/materials?sku=WAX-001” ```plaintext craftybase api [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for api ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase](/reference/craftybase/) - Official CLI for the Craftybase Public API # craftybase auth > Reference for the craftybase auth command. ## craftybase auth [Section titled “craftybase auth”](#craftybase-auth) Manage authentication credentials ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for auth ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase](/reference/craftybase/) - Official CLI for the Craftybase Public API * [craftybase auth login](/reference/craftybase_auth_login/) - Authenticate with the Craftybase API * [craftybase auth logout](/reference/craftybase_auth_logout/) - Remove stored credentials * [craftybase auth status](/reference/craftybase_auth_status/) - Show current authentication status # craftybase auth login > Reference for the craftybase auth login command. ## craftybase auth login [Section titled “craftybase auth login”](#craftybase-auth-login) Authenticate with the Craftybase API ### Synopsis [Section titled “Synopsis”](#synopsis) Authenticate with the Craftybase API using an API key. The key can be provided via: * —token flag * stdin (when piped) * interactive prompt (when run in a terminal) On success, credentials are saved to \~/.craftybase/config.toml. ```plaintext craftybase auth login [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for login --token string API token to authenticate with ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase auth](/reference/craftybase_auth/) - Manage authentication credentials # craftybase auth logout > Reference for the craftybase auth logout command. ## craftybase auth logout [Section titled “craftybase auth logout”](#craftybase-auth-logout) Remove stored credentials ```plaintext craftybase auth logout [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for logout ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase auth](/reference/craftybase_auth/) - Manage authentication credentials # craftybase auth status > Reference for the craftybase auth status command. ## craftybase auth status [Section titled “craftybase auth status”](#craftybase-auth-status) Show current authentication status ```plaintext craftybase auth status [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for status ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase auth](/reference/craftybase_auth/) - Manage authentication credentials # craftybase completion > Reference for the craftybase completion command. ## craftybase completion [Section titled “craftybase completion”](#craftybase-completion) Generate shell completion scripts ### Synopsis [Section titled “Synopsis”](#synopsis) Generate shell completion scripts for craftybase. To load completions: Bash: $ source <(craftybase completion bash) Zsh: $ source <(craftybase completion zsh) Fish: $ craftybase completion fish | source PowerShell: PS> craftybase completion powershell | Out-String | Invoke-Expression ```plaintext craftybase completion [bash|zsh|fish|powershell] ``` ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for completion ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase](/reference/craftybase/) - Official CLI for the Craftybase Public API # craftybase components > Reference for the craftybase components command. ## craftybase components [Section titled “craftybase components”](#craftybase-components) Manage components ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for components ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase](/reference/craftybase/) - Official CLI for the Craftybase Public API * [craftybase components list](/reference/craftybase_components_list/) - List components * [craftybase components show](/reference/craftybase_components_show/) - Show a single component # craftybase components list > Reference for the craftybase components list command. ## craftybase components list [Section titled “craftybase components list”](#craftybase-components-list) List components ```plaintext craftybase components list [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext --all Fetch all pages and render as a single table --category string Filter by category name -h, --help help for list --name string Filter by name (substring match) --page int Page number (1-based) --per-page int Items per page (server clamps to 100) --sku string Filter by SKU (exact match) --state string Filter by state: active, archived, all ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase components](/reference/craftybase_components/) - Manage components # craftybase components show > Reference for the craftybase components show command. ## craftybase components show [Section titled “craftybase components show”](#craftybase-components-show) Show a single component ```plaintext craftybase components show [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for show ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase components](/reference/craftybase_components/) - Manage components # craftybase materials > Reference for the craftybase materials command. ## craftybase materials [Section titled “craftybase materials”](#craftybase-materials) Manage materials ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for materials ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase](/reference/craftybase/) - Official CLI for the Craftybase Public API * [craftybase materials list](/reference/craftybase_materials_list/) - List materials * [craftybase materials show](/reference/craftybase_materials_show/) - Show a single material # craftybase materials list > Reference for the craftybase materials list command. ## craftybase materials list [Section titled “craftybase materials list”](#craftybase-materials-list) List materials ### Synopsis [Section titled “Synopsis”](#synopsis) List materials from your Craftybase account. Filter by SKU, name, category, or state. Use —all to fetch all pages, or —ndjson for streaming NDJSON output suitable for data pipelines. ```plaintext craftybase materials list [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext --all Fetch all pages and render as a single table --category string Filter by category name -h, --help help for list --name string Filter by name (substring match) --page int Page number (1-based) --per-page int Items per page (server clamps to 100) --sku string Filter by SKU (exact match) --state string Filter by state: active, archived, all ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase materials](/reference/craftybase_materials/) - Manage materials # craftybase materials show > Reference for the craftybase materials show command. ## craftybase materials show [Section titled “craftybase materials show”](#craftybase-materials-show) Show a single material ```plaintext craftybase materials show [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for show ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase materials](/reference/craftybase_materials/) - Manage materials # craftybase products > Reference for the craftybase products command. ## craftybase products [Section titled “craftybase products”](#craftybase-products) Manage products ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for products ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase](/reference/craftybase/) - Official CLI for the Craftybase Public API * [craftybase products list](/reference/craftybase_products_list/) - List products * [craftybase products show](/reference/craftybase_products_show/) - Show a single product # craftybase products list > Reference for the craftybase products list command. ## craftybase products list [Section titled “craftybase products list”](#craftybase-products-list) List products ```plaintext craftybase products list [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext --all Fetch all pages and render as a single table --category string Filter by category name -h, --help help for list --name string Filter by name (substring match) --page int Page number (1-based) --per-page int Items per page (server clamps to 100) --sku string Filter by SKU (exact match) --state string Filter by state: active, archived, all ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase products](/reference/craftybase_products/) - Manage products # craftybase products show > Reference for the craftybase products show command. ## craftybase products show [Section titled “craftybase products show”](#craftybase-products-show) Show a single product ```plaintext craftybase products show [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for show ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase products](/reference/craftybase_products/) - Manage products # craftybase version > Reference for the craftybase version command. ## craftybase version [Section titled “craftybase version”](#craftybase-version) Print version information ### Synopsis [Section titled “Synopsis”](#synopsis) Print the craftybase CLI version, commit, build date, and platform. ```plaintext craftybase version [flags] ``` ### Options [Section titled “Options”](#options) ```plaintext -h, --help help for version ``` ### Options inherited from parent commands [Section titled “Options inherited from parent commands”](#options-inherited-from-parent-commands) ```plaintext --api-url string API base URL (default: https://api.craftybase.com) --json Output raw API envelope (pretty-printed JSON) --ndjson Output auto-paginated NDJSON stream --no-color Disable ANSI color output --token string API token (overrides stored credentials) --verbose Show HTTP request/response detail (token redacted) ``` ### SEE ALSO [Section titled “SEE ALSO”](#see-also) * [craftybase](/reference/craftybase/) - Official CLI for the Craftybase Public API