🐈‍⬛ catify

Catify (cfy) is an independent, memory-efficient CLI aiming for behavioral compatibility with common Shopify CLI workflows. It is experimental and is not affiliated with, endorsed by, or sponsored by Shopify.

Compatibility	Memory Usage	Bundle Size	Load Time
73%	24.7x lower	2.9x smaller	93.6x faster

Measured on macOS arm64 against Shopify CLI 4.7.1: compatibility is 81 of 111 upstream commands implemented, memory is peak RSS, bundle size compares the 17 MB release binary with the 47 MB installed Shopify CLI package, and load time is median warm startup. See inventory/CLI-PARITY.md and benchmarks/results/latest.json.

Installation

npm (macOS, Linux, and Windows)

npm install --global catify-cli
cfy version
# `catify version` is equivalent

The npm package installs the native binary for the current OS and architecture. Node.js is only used during installation and as a small process launcher; Catify commands run in the Rust binary.

Installer script (macOS and Linux)

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/yan-ad/catify/main/install.sh | sh

The script installs to ~/.local/bin by default and verifies the release archive against the published SHA256SUMS. Override the destination with CFY_INSTALL_DIR=/usr/local/bin or install a specific release with CFY_VERSION=0.1.0.

See the complete installation guide for manual downloads, supported platforms, upgrades, uninstall steps, and npm publishing setup.

Development

cargo run -p cfy-cli -- --help
cargo test --workspace
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

Work is driven by the GitHub issue roadmap. Architecture and compatibility decisions live in docs/adr and docs/compatibility.md.

The generated CLI parity matrix tracks all 111 pinned Shopify CLI commands, including native/adapter status, automated test evidence, live verification, gaps, and the owning GitHub issue.

Configuration precedence, file locations, and persistence guarantees are documented in docs/configuration.md.

Pinned upstream research lives in docs/research, including the Shopify authentication flow and risk analysis.

CLI conventions

Global flags work before or after nested commands:

• -v, --verbose can be repeated to increase diagnostic detail.
• --no-color disables ANSI color output.
• --json requests machine-readable output from commands that support it.
• --non-interactive prevents commands from prompting.

The initial compatibility aliases are cfy a for cfy app, cfy th for cfy theme, cfy v for cfy version, and show for nested info commands.

Output and diagnostics

--json reserves stdout for one machine-readable command result. Runtime errors are emitted as JSON on stderr, so pipelines never receive human log lines on stdout. Diagnostic logs are disabled by default; pass -v to enable cause and debug details, or repeat it as future commands add finer levels.

Known Shopify token environment variables are redacted from human output, JSON values, errors, and debug causes. Commands must pass output through the shared Output boundary rather than writing directly to stdout or stderr.

Exit codes are stable by category:

Status	Categories
0	Success
1	Shopify API and external process failures
2	Invalid input, CLI usage, and configuration failures

Generate shell completion scripts with cfy completion <shell>, for example:

cfy completion bash > ~/.local/share/bash-completion/completions/cfy
cfy completion zsh > ~/.zfunc/_cfy
cfy completion fish > ~/.config/fish/completions/cfy.fish

Theme listing

List all available theme metadata with:

SHOPIFY_CLI_THEME_TOKEN=shptka_... cfy theme list --store example
cfy theme list --store example --json

Store resolution uses --store, then CFY_STORE, then the compatible SHOPIFY_FLAG_STORE, then the discovered project configuration. Theme access uses SHOPIFY_CLI_THEME_TOKEN until the interactive login command is wired. Pagination is automatic. Human output contains theme ID, role, and name; JSON returns the complete metadata objects. Authentication and permission failures include token-refresh and scope remediation without printing the token.

Pull selected theme assets into a local directory with repeatable wildcard filters:

SHOPIFY_CLI_THEME_TOKEN=shptka_... cfy theme pull \
  --store example --theme 123456789 \
  --include 'assets/*' --exclude '*.map' --destination ./theme

--include defaults to all assets when omitted; exclusions are applied after includes. Text and binary files are staged fully before the destination is changed. Unsafe paths and symlink traversal are rejected, and write failure or Ctrl-C triggers rollback so selected files are not left partially updated.

Push local changes back to a theme:

SHOPIFY_CLI_THEME_TOKEN=shptka_... cfy theme push \
  --store example --theme 123456789 --source ./theme

Only new and changed assets are uploaded. Remote-only assets are retained unless --allow-delete is explicitly supplied. A live theme requires confirmation; non-interactive automation must pass --force. Individual API failures produce a non-zero actionable summary while preserving the successful operation counts.

Run a development session with an initial sync and incremental watching:

SHOPIFY_CLI_THEME_TOKEN=shptka_... cfy theme dev --store example --source ./theme

Without --theme, catify creates a temporary development theme and deletes it when the session ends, including on Ctrl-C or a sync error. Pass --theme ID to reuse an existing theme; a user-supplied theme is never deleted. Lifecycle state, preview URL, and editor URL are printed clearly. Creates and updates upload, deletes remove the remote asset, and renames delete the old key and upload the new key. Noisy events are debounced and sync failures use bounded retry/backoff.