@timbenniks/contentstack-xzibit

A friendly interactive front‑end for the official Contentstack CLI (csdx): menus, session context (who is logged in, region), and safe passthrough when you already know the csdx arguments you need.

This is an independent open source tool. It is not affiliated with or endorsed by Contentstack; it simply invokes csdx on your machine.

Features

• Interactive menu for common flows (auth, config, tokens, TypeScript generation, plugins, content management helpers).
• Session summary before actions (login state, region) using the same probes as csdx.
• **xzibit raw** to forward any arguments to csdx without the wrapper getting in the way.
• Optional “plain” mode for scripts and CI (--no-fun / XZIBIT_SERIOUS=1).
• Resolves csdx on your PATH, or falls back to npx @contentstack/cli with a one‑time hint (see below).

Requirements

| Requirement | Notes | | -------------------- | ------------------------------------------------------------------------------------------------------------------- | | Node.js | 18 or newer | | Contentstack CLI | Peer dependency @contentstack/cli >= 1.0.0. A global install is recommended; see Prerequisites. |

Prerequisites

You need the Contentstack CLI available in one of these ways:

1. Global install (recommended) — puts csdx on your PATH:

 npm install -g @contentstack/cli

2. Via npx — if csdx is not found, xzibit runs npx @contentstack/cli …. That can be slower and may download packages. A one‑time message is printed to stderr; set XZIBIT_NO_NPX_HINT=1 to hide it.

For day‑to‑day use, match a recent 1.x @contentstack/cli (see devDependencies in package.json for what CI tests against). Very old majors may lack flags xzibit expects—upgrade csdx if a command fails.

Installation

From npm (after the package is published):

npm install -g @timbenniks/contentstack-xzibit

Scoped packages are private on npm by default; the first public publish must be run with npm publish --access public (unless you use an org that defaults to public).

Entry points: **xzibit** and **csxz** (same binary).

From source (contributors and local testing): clone this repository, then from the project root:

npm install
npm run build
npm link   # optional: makes `xzibit` available globally on this machine

Run node dist/cli.js --help without npm link if you prefer not to link.

Usage

Interactive

xzibit          # default: open the menu
xzibit menu     # same

Subcommands

| Command | Purpose | | -------------------- | ------------------------------------------------------ | | xzibit auth | Auth menu (login, logout, whoami, tokens) | | xzibit config | Interactive CLI config (region, logs, proxy, …) | | xzibit login | Quick csdx auth:login flow | | xzibit region | Quick region preset (csdx config:set:region) | | xzibit tokens | List / add / remove / replace token aliases | | xzibit tsgen | TypeScript generation (csdx tsgen) | | xzibit plugins | Plugin management menu | | xzibit cm | Export, import, or audit stack content (cm:stacks:*) | | xzibit raw <args…> | Forward arguments to csdx (non‑interactive) |

Examples:

xzibit raw auth:whoami
xzibit raw -- auth:whoami    # same; `--` optional after `raw`

Global options (apply to the default interactive entry as well):

• --no-fun — plain header, no decorative banner.
• --chaos — chaos‑only taglines (for the default banner experience).
• --drama — extra banner line (or set XZIBIT_DRAMA=1).

xzibit --help lists everything Commander registers.

Environment variables

| Variable | Effect | | ---------------------- | ---------------------------------------------------------------------- | | XZIBIT_SERIOUS=1 | Same idea as --no-fun (plain output). | | XZIBIT_CHAOS=1 | Chaos taglines only (with fun mode). | | XZIBIT_DRAMA=1 | Extra theatrical banner line. | | XZIBIT_NO_NPX_HINT=1 | Suppress the stderr hint when falling back to npx @contentstack/cli. |

Optional project tagline

In the current working directory you can add **xzibit.json** with { "tagline": "…" } to show a custom line under the main tagline in the banner (ignored in serious mode).

Troubleshooting

| Symptom | What to try | | --------------------------------- | ----------------------------------------------------------------------- | | Could not run npx / ENOENT | Ensure Node is installed and on your PATH. | | Could not run csdx | Install the CLI globally: npm install -g @contentstack/cli. | | Slow first run without global CLI | Expected when using npx; install csdx globally for a stable binary. |

Security

CLI commands and tokens may appear in process listings on your machine (same as using csdx directly). See SECURITY.md for reporting and operational notes.

Contributing

Issues and pull requests are welcome. Before opening a PR:

npm install
npm run lint
npm run typecheck
npm test
npm run build

Please keep changes focused and consistent with existing style. For security‑sensitive reports, use the process in SECURITY.md.

License

MIT

Changelog

See CHANGELOG.md.