npm package: @swazipen/cli
Description: An npm swazipen build, just install and use it globally
Author: godieGH
Latest version: 1.2.0

# @swazipen/cli — Quickstart & Reference

> A lightweight CLI wrapper for Swazipen tools that lets SwaziLang developers and beginners install and use Swazipen quickly via npm or pnpm — no cloning or rebuild required.

---

# Table of Contents

1. [Overview](#overview)
2. [Requirements](#requirements)
3. [Installation](#installation)
4. [Basic Usage](#basic-usage)
5. [CLI Reference](#cli-reference)
   - [Arguments](#arguments)
   - [Flags](#flags)
6. [Notes & Best Practices](#notes--best-practices)
7. [References](#references)
8. [License & Contributing](#license--contributing)


---

## Overview

`@swazipen/cli` packages Swazipen's build into an easy-to-install global CLI. Install it once (via `npm` or `pnpm`) and run `swazipen` from any directory to scan projects, start the browser-based editor, run the built-in server, and execute SwaziLang files (when the SwaziLang executable is available on your system).

All features available in the main Swazipen project are included in this CLI package and it will be updated as Swazipen evolves. For full/core documentation and advanced usage, consult the Swazipen GitHub repository.

- Swazipen ship a version of its build into a npm package
- This cli tool make it easy for SwaziLang devs and biginers to easily `npm install @swazipen/cli -g` and  grab the ready-to-use swazipen cli,  Just easy like that than cloning the github repository and re-build processes
- This cli package will be updated as swazipen updates, all the features from swazipen will be included in here
- for core documantation of how to use swazipen you can find them in the github repository [swazipen](https://github.com/godieGH/SwaziPen#readme)
- in here you will get some basic npm basics to install and use swazipen cli


---

## Requirements

- Node.js and npm (or pnpm) installed.
- **SwaziLang executable** built and installed on your machine **if you want the editor's run/execute on-the-fly features** to work. See the Swazipen repository for build instructions.
- Ensure the SwaziLang executable is placed in a directory that is included in your system `PATH` so the `swazipen` CLI can call it.


**Note: you will need `SwaziLang` excutable installed in your machine for the swazipen editor on the fly features to work**
- build the excutable from [SwaziLang](https://github.com/godieGH/SwaziLang),  
- read how to build it from [here](https://github.com/godieGH/SwaziPen#1-build-swazilang)
- Ensure it is in your system $PATH to be accessible by the `swazipen` cli


---

## Installation

You can install the CLI globally using either npm or pnpm:

```bash
# Using npm
npm install -g @swazipen/cli

# Recommended: using pnpm
pnpm add -g @swazipen/cli
```

After installation the `swazipen` command will be available globally and can be run from any location in your terminal.

If you prefer the advanced approach (cloning the repository and building from source), head to the Swazipen GitHub repo for instructions and development notes.

---

## Basic Usage

Scan a project (defaults to current working directory):

```bash
swazipen <path>
```

If you omit `<path>`, `swazipen` will scan the current working directory (`.`). Example:

```bash
swazipen .
```

The CLI starts the built-in browser editor and a local server so you can create, edit, rename, move, and execute SwaziLang files in the browser (requires the SwaziLang executable for execution features).

### Recommended usage tips
- Run `swazipen` in your project root (or the directory you want scanned).
- Avoid scanning system directories, large monorepos, or folders with millions of files — this may slow or break the scan.
- Do not run `swazipen` on folders you don't have permission to read; the CLI will fail when it encounters unreadable files or protected paths.

---

## CLI Reference

### Arguments

| Argument | Description |
|---|---|
| `<path>` | Path to scan as a project. Defaults to `.` (current working directory). |

### Flags

| Flag | Description |
|---|---|
| `--port <port>` or `-p <port>` | Run the web editor on the specified port. Default: `5000`. |
| `--quiet` or `-q` | Run the CLI with minimal logging (only errors). |

Examples:

```bash
# Scan the current directory and open the editor on default port 5000
swazipen .

# Scan a project and run the editor on port 8080
swazipen /path/to/project --port 8080

# Run with minimal logs
swazipen . --quiet
```

---

## Notes & Best Practices

- **Permissions:** Don't point `swazipen` at secured or protected folders. Permission errors will stop the scan. If you need to scan a folder that requires elevated privileges, either run the CLI with appropriate permissions or choose a different target directory.
- **Keep scans focused:** For best performance, scan only the project directory (not parent folders or the entire drive). Avoid scanning node_modules or other large dependency folders unless necessary.
- **Keep SwaziLang executable in `PATH`:** The browser editor's run/execution feature depends on the SwaziLang executable being available in your `PATH`. Follow the SwaziLang build instructions in the Swazipen repo to produce the executable.
- **Updates:** This CLI is distributed as an npm package and will be updated when Swazipen releases new builds. To update, run the usual package update commands (e.g., `npm update -g @swazipen/cli` or `pnpm update -g @swazipen/cli`).

---

## References

- Core and advanced documentation: see the Swazipen GitHub repository (search for Swazipen on GitHub).
- Read more documantation on the [github repo.](https://github.com/godieGH/SwaziPen#swazipen) of swazipen to understand variety of using the tool

---

## License & Contributing.
- See the Swazipen repository for license terms and contribution guidelines if you want to contribute or build from source.
---