<div align="center">

<a href="https://oprajs.com">
  <img src="https://oprajs.com/img/opra-header-block.webp" width="880" alt="OPRA — Open Platform for Rich APIs" />
</a>

# @opra/cli

CLI tools for the OPRA framework — generate typed clients with `oprimp`

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![CI Tests][ci-test-image]][ci-test-url]
[![Test Coverage][coveralls-image]][coveralls-url]

[🌐 Documentation](https://oprajs.com) · [🚀 Getting Started](https://oprajs.com/docs/introduction) · [📦 Packages](https://github.com/panates/opra#packages) · [💬 Issues](https://github.com/panates/opra/issues)

</div>

---

`@opra/cli` is a command-line tool for OPRA (Open Platform for Richful APIs). It currently features `oprimp`, a
TypeScript code generator that creates client-side models and API services from an OPRA service.

## Installation

You can install `@opra/cli` globally or as a development dependency in your project.

### Global Installation

```bash
npm install -g @opra/cli
```

### Local Installation

```bash
npm install --save-dev @opra/cli
```

## CLI Usage: oprimp

The `oprimp` tool generates TypeScript code from an OPRA service URL.

```bash
oprimp <serviceUrl> <outDir> [options]
```

### Arguments

- `serviceUrl`: The URL of the OPRA service (e.g., `http://localhost:3000/opra`).
- `outDir`: The output directory where the generated files will be saved.

### Options

- `--ext`: Adds `.js` extension to imports. This is useful for ESM projects.
- `--refns`: Exports referenced API documentation with namespaces.
- `--no-color`: Disables colors in log messages.
- `-v, --version`: Displays the version number.
- `-h, --help`: Displays help information.

### Examples

#### Basic Usage

Generate TypeScript code from a local OPRA service:

```bash
npx oprimp http://localhost:3000/opra ./src/generated
```

#### ESM Projects

If your project uses ESM and requires file extensions in imports:

```bash
npx oprimp http://localhost:3000/opra ./src/generated --ext
```

## Programmatic Usage

You can also use the `TsGenerator` class programmatically in your scripts.

```typescript
import { TsGenerator } from '@opra/cli';

async function generate() {
  const generator = new TsGenerator({
    serviceUrl: 'http://localhost:3000/opra',
    outDir: './src/generated',
    importExt: true, // Optional: add .js extensions
    fileHeader: '/* Generated by OPRA */', // Optional: add a header to files
  });

  await generator.generate();
  console.log('Generation completed!');
}

generate().catch(console.error);
```

### TsGenerator Options

| Option                | Type      | Description                                                    |
|-----------------------|-----------|----------------------------------------------------------------|
| `serviceUrl`          | `string`  | **Required**. The URL of the OPRA service.                     |
| `outDir`              | `string`  | **Required**. The output directory for the generated files.    |
| `cwd`                 | `string`  | The current working directory. Defaults to `process.cwd()`.    |
| `logger`              | `ILogger` | Logger instance for outputting information.                    |
| `fileHeader`          | `string`  | Optional header text to add to the top of each generated file. |
| `importExt`           | `boolean` | Whether to add `.js` extension to imports.                     |
| `referenceNamespaces` | `boolean` | Whether to export references with namespaces.                  |

## Support

You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/opra/issues) page.

## Node Compatibility

- node >= 20.x

## License

Available under [MIT](LICENSE) license.

[npm-image]: https://img.shields.io/npm/v/@opra/cli

[npm-url]: https://npmjs.org/package/@opra/cli

[downloads-image]: https://img.shields.io/npm/dm/@opra/cli.svg

[downloads-url]: https://npmjs.org/package/@opra/cli

[ci-test-image]: https://github.com/panates/opra/actions/workflows/test.yml/badge.svg

[ci-test-url]: https://github.com/panates/opra/actions/workflows/test.yml

[coveralls-image]: https://coveralls.io/repos/github/panates/opra/badge.svg?branch=dev

[coveralls-url]: https://coveralls.io/github/panates/opra?branch=dev
