# @timbenniks/contentstack-xzibit

A friendly **interactive front‑end** for the official [Contentstack CLI](https://www.contentstack.com/docs/developers/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). |


## Prerequisites

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

1. **Global install (recommended)** — puts `csdx` on your `PATH`:
  ```bash
   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):

```bash
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:

```bash
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

```bash
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:

```bash
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](./SECURITY.md) for reporting and operational notes.

## Contributing

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

```bash
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](./SECURITY.md).

## License

[MIT](./LICENSE)

## Changelog

See [CHANGELOG.md](./CHANGELOG.md).