# quaaant-cli

> Quaaant CLI: A command-line interface for integrating and managing Quaaant design assets.

Latest version **1.0.3** (published 2024-04-25) · SEE LICENSE IN LICENSE license · 0 weekly downloads

## Install

```sh
npm install quaaant-cli
pnpm add quaaant-cli
yarn add quaaant-cli
bun add quaaant-cli
```

Provides the command `quaaant`.

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2024-04-25 |
| First published | 2024-04-23 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 210.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Quaaant Labs LTD |
| Maintainers | quaaant-labs |
| Keywords | quaaant, design, assets, asset-management, creative-workflow, adobe, illustrator, photoshop, figma, UI, UX |

## Links

- npm: https://www.npmjs.com/package/quaaant-cli
- npm.io page: https://npm.io/package/quaaant-cli

## Dependencies (4)

- [ansis](https://npm.io/package/ansis.md) ^3.1.1
- [axios](https://npm.io/package/axios.md) ^1.6.2
- [dotenv](https://npm.io/package/dotenv.md) ^16.3.1
- [commander](https://npm.io/package/commander.md) ^12.0.0

## Alternatives

- [@progress/kendo-ooxml](https://npm.io/package/@progress/kendo-ooxml.md) — 152.1K weekly downloads
- [@progress/kendo-react-ripple](https://npm.io/package/@progress/kendo-react-ripple.md) — 8.0K weekly downloads
- [@progress/kendo-react-orgchart](https://npm.io/package/@progress/kendo-react-orgchart.md) — 4.3K weekly downloads
- [@praxisui/dynamic-fields](https://npm.io/package/@praxisui/dynamic-fields.md) — 2.4K weekly downloads
- [@mesalvo/react-ui](https://npm.io/package/@mesalvo/react-ui.md) — 1.7K weekly downloads

## Recent versions

- 1.0.3 (latest) — 2024-04-25
- 1.0.2 — 2024-04-23
- 1.0.1 — 2024-04-23
- 1.0.0 — 2024-04-23

## README

# Quaaant CLI documentation


## Overview

The Quaaant NPM package offers a command-line interface (CLI) that enables developers to seamlessly integrate and manage digital design assets from the Quaaant platform into their JavaScript projects.

This tool provides a powerful and flexible way to integrate Quaaant design assets into your development workflows, ensuring assets are up-to-date and correctly configured according to your project specifications.


## Key features

- **Direct access to design assets:** Pull assets directly into your projects from designs created in Adobe Illustrator, Photoshop, or Figma using the Quaaant platform. This integration ensures a smooth workflow from design to development.

- **Custom configuration:** Fine-tune how assets are incorporated into your project with extensive configuration options.

- **Simple update process:** Update your assets easily with a simple command. This command can be integrated into your automatic build process, allowing updates to be seamlessly incorporated into your workflow whenever you deploy or build your project.


## Installation

To install the Quaaant CLI globally, use the following command:

```bash
npm install -g quaaant-cli
```
After installation, you can use the `quaaant init` command to generate a `.env` file and an example `quaaant-config.json` file in your project’s root directory.

```bash
quaaant init
```

## Setup instructions

### Environment configuration

After running `quaaant init`, visit the Quaaant app at https://app.quaaant.com/dev-tokens. Create your development token by selecting the projects it should be associated with. This token authenticates your requests to the Quaaant API.

Open the `.env` file in your project’s root directory and replace `"your_development_token_here"` with your development token:

```js
QUAAANT_DEV_TOKEN="your_development_token_here"
```

### Configuration file

The `quaaant init` command also creates a `quaaant-config.json` file in your project’s root directory. This configuration file specifies the rules and parameters for asset integration, ensuring that they are managed according to your specific project requirements.

You can modify this file to define asset handling for each project.

**Example Configuration:**

```json
{
    "quaaantConfigVersion": 1,
    "projects": [
        {
            "uuid": "example-project-uuid",
            "branch": "feature/new-ui",
            "path": "assets/ui-elements",
            "subfolders": true,
            "subfolderSeparator": "_",
            "clearBeforePull": true,
            "prefix": "quaaant-",
            "suffix": "-v1.2",
            "options": {
                "omitColors": true
            }
        },
        {
            "uuid": "another-project-uuid",
            "path": "assets",
            "assets": [
                "asset1-name",
                "asset2-name"
            ]
        }
    ]
}
```

This configuration file allows for detailed control over asset management, from directory structure and file naming conventions to selective asset integration.


## Configuration options

This section provides a detailed explanation of the key configuration options available in the `quaaant-config.json` file. Each option is designed to optimize how assets are managed and integrated into your projects.

| Option | Description | Mandatory | Default |
|--------|-------------|-----------|---------|
| [`uuid`](#uuid) | Unique identifier for the Quaaant project | Yes | None |
| [`branch`](#branch) | Specifies the branch of the project assets to be pulled | No | `main` |
| [`path`](#path) | The local directory path where the assets will be saved, relative to the project root | No | Project root |
| [`assets`](#assets) | An array of asset names that you want to pull from the project | No | All assets |
| [`subfolders`](#subfolders) | Determines whether to organize downloaded assets into subfolders | No | `false` |
| [`subfolderSeparator`](#subfolderseparator) | The character used to separate different sections of the asset name | No | `_` |
| [`clearBeforePull`](#clearbeforepull) | Determines whether to delete the existing contents of the specified path | No | `false` |
| [`prefix`](#prefix) | String to prepend to the names of downloaded assets | No | None |
| [`suffix`](#suffix) | String to append to the names of downloaded assets | No | None |
| [`options`](#options) | A set of additional settings that can be configured per project | No | None |

### `uuid`

The `uuid` property is a unique identifier for the Quaaant project from which assets are to be pulled.

#### Example

```json
"uuid": "example-project-uuid"
```

To locate the UUID required for your configuration, navigate to the “Dev Tokens” page on the Quaaant app by following this link: https://app.quaaant.com/dev-tokens. Once there, select the specific token relevant to your project.

A modal window will appear displaying a list of associated projects for that token. Next to each project name, there is a ‘Copy’ button which allows you to easily copy the UUID for the project you wish to configure. This UUID is essential for linking your project configuration to the correct assets on the Quaaant platform.

### `branch`

Specifies the branch of the project assets to be pulled. This can be useful for managing different versions, stages of asset development, or for experimenting with new designs.

#### Examples

Specific feature branch:
```json
"branch": "feature/new-ui"
```

Release branch:
```json
"branch": "release/2023-q1"
```

If not specified, assets will be pulled from the `main` branch.

### `path`

The local directory path where the assets will be saved. The path should be relative to the project’s root.

#### Examples

Specific directory:
```json
"path": "assets/ui-elements"
```

Generic directory:
```json
"path": "assets"
```

If no `path` is specified, assets will be saved directly in the project’s root directory.

### `assets`

An array of asset names that you want to pull from the project. If this option is specified, only the assets with the names in this array will be pulled. If this option is not specified, all assets from the project will be pulled.

#### Example

```json
"assets": [
    "asset1-name",
    "asset2-name"
]
```

### `subfolders`

Determines whether to organize downloaded assets into subfolders based on their names. If a separator is detected in the asset name, it will be used as a path separator for creating the asset’s path.

For example, if the asset name is `icons_home.svg` and the `subfolderSeparator` is set to `_`, then the asset will be saved as `/icons/home.svg`.

#### Example

Subfolders from asset name:
```json
{
    "subfolders": true,
    "subfolderSeparator": "_"
}
```

### `subfolderSeparator`

The character used to separate different sections of the asset name, which dictates how subfolders are named. Only relevant if `subfolders` is `true`.

#### Examples

Underscore separator:
```json
"subfolderSeparator": "_"
```

Dash separator:
```json
"subfolderSeparator": "-"
```

### `clearBeforePull`

Determines whether to delete the existing contents of the specified path before downloading new assets. Please note that if an asset with the same name is pulled, it will overwrite the existing asset regardless of this setting.

#### Example

Clear folder before pulling new assets:
```json
"clearBeforePull": true
```

### `prefix`

The `prefix` option allow you to prepend a string to the names of downloaded assets, which can help in organizing or versioning files.

#### Examples

Branding:
```json
"prefix": "quaaant-"
```

Departmental categorization:
```json
"prefix": "marketing-"
```

Adding a prefix helps in identifying and sorting assets more efficiently within your project structure.

### `suffix`

The `suffix` option allows you to append a string to the names of downloaded assets. This can be particularly helpful for versioning files or specifying certain attributes that help in asset management.

#### Examples

Versioning:
```json
"suffix": "-v1.2"
```

Localization:
```json
"suffix": "-en"
```

Project phase:
```json
"suffix": "-beta"
```

### `options`

A set of additional settings that can be configured per project, such as omitting color information from the downloaded assets.

#### Example

```json
"options": {
    "omitColors": true
}
```


## Usage

To initiate the synchronization of assets with your project, run the following command from the root directory of your project:

```bash
quaaant sync
```

This command activates the asset pull process as outlined in your `quaaant-config.json` file. It intelligently manages the download and organization of various asset types according to the configurations you’ve specified.

---
_Source: https://npm.io/package/quaaant-cli · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._