cloudly/ts_cliclient/readme.md

# @serve.zone/cli

A comprehensive command-line interface (CLI) tool for managing multi-cloud environments, leveraging the features of the @serve.zone/cloudly platform. This CLI is crafted to facilitate seamless interactions with complex cloud configurations and deployments, utilizing Docker Swarmkit orchestration.

## Install

To begin using the `@serve.zone/cli` in your projects, install it via npm by running:

```bash
npm install @serve.zone/cli --save
```

This command will download the package and integrate it into your project's `node_modules` directory, reflecting the dependency in your `package.json`.

## Usage

The `@serve.zone/cli` is a powerful command-line tool aimed at developers and system administrators who are managing containerized applications across various cloud platforms. Through this CLI, users can interact with their cloud infrastructure efficiently, enabling and extending `Cloudly’s` capabilities directly from the terminal.

### Prerequisites

Before proceeding to use the `@serve.zone/cli`, ensure your system meets the following prerequisites:
- Latest Node.js LTS version installed.
- Familiarity with basic command-line operations.
- Properly configured cloud service accounts (like Cloudflare, Hetzner), necessary for managing respective services.

### Setting Up the CLI

Begin setting up the `Cloudly` instance for CLI usage:
```typescript
// Import required modules
import { Cloudly } from '@serve.zone/cloudly';
import * as path from 'path';

// Define the configuration needed for cloud operations
const cloudlyConfig = {
  cfToken: 'your-cloudflare-token',
  hetznerToken: 'your-hetzner-token',
  environment: 'production',
  publicUrl: 'your-public-url',
};

// Instantiate and start the Cloudly instance
const cloudlyInstance = new Cloudly(cloudlyConfig);
await cloudlyInstance.start();

// Log the setup information to ensure it’s correct
console.log(`Cloudly is set up at ${cloudlyInstance.config.data.publicUrl}`);
```

This snippet initializes a Cloudly instance with necessary environment configuration, setting the groundwork for all subsequent CLI operations.

### Core Operations with the CLI

Here's how you leverage various operational commands within the CLI feature:

#### Managing Clusters

To create, list, and delete clusters, you’ll require invoking the `Cloudly` class with its cluster management logic:

```typescript
// Module imports
import { Cloudly } from '@serve.zone/cloudly';

// Async function for cluster management
async function manageCluster() {
  // Prepare configuration
  const config = {
    cfToken: 'YOUR_CLOUDFLARE_TOKEN',
    hetznerToken: 'YOUR_HETZNER_TOKEN',
  };

  // Initialize Cloudly
  const cloudlyInstance = new Cloudly(config);
  await cloudlyInstance.start();

  // Example: Creating a new cluster
  const cluster = await cloudlyInstance.clusterManager.createCluster({
    id: 'example_cluster_id',
    data: {
      name: 'example_cluster',
      servers: [],
      sshKeys: [],
    }
  });
  
  // Log cluster details
  console.log('Cluster created:', cluster);
}
```
With the above example, you can dynamically manage cluster configurations, ensuring your application components are effectively orchestrated across cloud environments.

#### Deploying Services

Deploying cloud-native services within your clusters can be achieved through the CLI:

```typescript
import { Cloudly } from '@serve.zone/cloudly';

// Function to handle service deployment
async function deployService() {
  const config = {
    cfToken: 'YOUR_CLOUDFLARE_TOKEN',
    hetznerToken: 'YOUR_HETZNER_TOKEN',
  };

  const cloudlyInstance = new Cloudly(config);
  await cloudlyInstance.start();

  // Deploy a new service to a specified cluster
  const newService = {
    id: 'example_service_id',
    data: {
      name: 'example_service',
      imageId: 'example_image_id',
      imageVersion: '1.0.0',
      environment: {},
      ports: { web: 80 }
    }
  };

  // Store service into database and deploy
  console.log('Deploying service:', newService)
  await cloudlyInstance.serverManager.deployService(newService);
}

deployService();
```

By streamlining your service deployments through CLI, you ensure reproducibility and clarity in development operations.

#### Managing Certificates

Ensuring secure connections by managing SSL certificates is essential. The CLI aids in this through Let's Encrypt integration:

```typescript
import { Cloudly } from '@serve.zone/cloudly';

// Function to acquire a certificate
async function getCertificate() {
  const config = {
    cfToken: 'YOUR_CLOUDFLARE_TOKEN',
    hetznerToken: 'YOUR_HETZNER_TOKEN',
  };

  const cloudlyInstance = new Cloudly(config);
  await cloudlyInstance.start();

  // Fetch certificate using Let's Encrypt
  const domainName = 'example.com';
  const cert = await cloudlyInstance.letsencryptConnector.getCertificateForDomain(domainName);
  console.log(`Obtained certificate for domain ${domainName}:`, cert);
}

getCertificate();
```

This process facilitates the automation of SSL certificates provisioning, ensuring high security in your apps.

### Automating Tasks with the CLI

Task scheduling is a feature you can utilize to automate recurring processes. Here’s an example of how `@serve.zone/cli` accomplishes task scheduling:

```typescript
import { TaskBuffer } from '@push.rocks/taskbuffer';

// Schedule a task to run every day
const dailyTask = new TaskBuffer({
  schedule: '0 0 * * *', // Using cron schedule
  taskFunction: async () => {
    console.log('Performing daily backup check...');
    // Include backup logic here
  },
});

// Initiate task scheduling
dailyTask.start();
```

Scheduled tasks like periodic maintenance, data synchronization, or backups ensure you keep your cloud environment robust and reliable.

### Integrating Third-Party APIs

Expand the scope of your applications with API integrations offered via `@serve.zone/cli`:

```typescript
import { Cloudly } from '@serve.zone/cloudly';

// Function to send notifications
async function sendNotification() {
  const cloudlyConfig = {
    cfToken: 'your-cloudflare-token',
    hetznerToken: 'your-hetzner-token',
  };

  const cloudly = new Cloudly(cloudlyConfig);
  await cloudly.start();

  // Configure and send push notification
  await cloudly.externalApiManager.sendPushMessage({
    deviceToken: 'some_device_token',
    message: 'Hello from Cloudly!',
  });
}

sendNotification();
```

API integrations via the CLI extend Cloudly’s reach, enabling comprehensive service interconnections.

### Security and Access Management

Effective identity management is possible through `@serve.zone/cli`. Manage user roles, token validations, and more:

```typescript
import { Cloudly } from '@serve.zone/cloudly';

// Configuring and verifying identity
async function authenticateUser() {
  const cloudlyConfig = {
    cfToken: 'your-cloudflare-token',
    hetznerToken: 'your-hetzner-token',
  };

  const cloudly = new Cloudly(cloudlyConfig);
  await cloudly.start();

  // Sample user credentials
  const userIdentity = {
    userId: 'unique_user_id',
    jwt: 'user_jwt_token',
  };

  // Validate identity
  const isValid = cloudly.authManager.validateIdentity(userIdentity);
  console.log(`Is user identity valid? ${isValid}`);
}

authenticateUser();
```

The applications of identity validation streamline operational security and enforce access controls across your systems.

These examples offer a glimpse into the vast potential of @serve.zone/cli, which combines automation, security, and flexibility for state-of-the-art cloud management. You are encouraged to build upon this documentation to harness Cloudly's full capabilities in your infrastructure and process ecosystems. Let the CLI transform your cloud management experience with precision and adaptability.

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.