Skip to content

Commit

Permalink
docs(ormus): add cli doc (#115)
Browse files Browse the repository at this point in the history
  • Loading branch information
@gohossein
gohossein authored Jul 31, 2024
1 parent 38fa2a6 commit 5230c60
Showing 1 changed file with 280 additions and 0 deletions.
280 changes: 280 additions & 0 deletions doc/cli.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,280 @@
Based on the core entities in your **Ormus** CDP platform **User**, **Project**, **Source**, **Destination**, and **Connection** here's a comprehensive list of CLI commands using `ormus` as the command prefix. These commands are designed to manage the lifecycle and interactions of these entities:

### 1. **User Management**
- **User Registration and Authentication**
- `ormus user register --email <email>`: Register a new user with an email.
- `ormus user login --email <email>`: Log in as a user.
- `ormus user logout`: Log out the current user.

- **User Account Management**
- `ormus user show`: Display details of the logged-in user.
- `ormus user update --email <new-email> [--name <name>]`: Update user details.
- `ormus user delete`: Delete the logged-in user's account.

### 2. **Project Management**
- **Create, View, and Manage Projects**
- `ormus project create --name <project-name>`: Create a new project.
- `ormus project list`: List all projects associated with the user.
- `ormus project show --project-id <project-id>`: Display details of a specific project.
- `ormus project update --project-id <project-id> --name <new-name>`: Update project details.
- `ormus project delete --project-id <project-id>`: Delete a specific project.

### 3. **Source Management**
- **Define and Manage Sources**
- `ormus source create --project-id <project-id> --name <source-name> --type <source-type>`: Create a new source within a project.
- `ormus source list --project-id <project-id>`: List all sources for a specific project.
- `ormus source show --project-id <project-id> --source-id <source-id>`: Show details of a specific source.
- `ormus source update --project-id <project-id> --source-id <source-id> --name <new-name>`: Update a source's details.
- `ormus source delete --project-id <project-id> --source-id <source-id>`: Delete a source.
- `ormus source enable --project-id <project-id> --source-id <source-id>`: Enable a source
- `ormus source disable --project-id <project-id> --source-id <source-id>`: Disable a source
- `ormus source get-write-key --project-id <project-id> --source-id <source-id>`: Get write-key of a source
- `ormus source rotate-write-key --project-id <project-id> --source-id <source-id>`: Rotate write-key for a source


### 4. **Destination Management**
- **Set Up and Manage Destinations**
- `ormus destination create --project-id <project-id> --name <destination-name> --type <destination-type>`: Create a new destination within a project.
- `ormus destination list --project-id <project-id>`: List all destinations for a specific project.
- `ormus destination show --project-id <project-id> --destination-id <destination-id>`: Show details of a specific destination.
- `ormus destination update --project-id <project-id> --destination-id <destination-id> --name <new-name>`: Update a destination's details.
- `ormus destination delete --project-id <project-id> --destination-id <destination-id>`: Delete a destination.
- `ormus destination enable --project-id <project-id> --destination-id <destination-id>`: Enable a destination
- `ormus destination disable --project-id <project-id> --destination-id <destination-id>`: Disable a destination
- `ormus destination test-connection --project-id <project-id> --destination-id <destination-id>`: Test the connection of a destination

### 5. **Connection Management**
- **Create and Manage Connections**
- `ormus connection create --project-id <project-id> --source-ids <source-ids> --destination-ids <destination-ids> [--config <config-file>]`: Create a new connection between sources and destinations.
- `ormus connection list --project-id <project-id>`: List all connections for a specific project.
- `ormus connection show --project-id <project-id> --connection-id <connection-id>`: Show details of a specific connection.
- `ormus connection update --project-id <project-id> --connection-id <connection-id> [--config <new-config-file>]`: Update connection settings.
- `ormus connection delete --project-id <project-id> --connection-id <connection-id>`: Delete a connection.
- `ormus connection enable --project-id <project-id> --connection-id <connection-id>`: Enable a connection
- `ormus connection disable --project-id <project-id> --connection-id <connection-id>`: Disable a connection
- `ormus connection add-source --project-id <project-id> --connection-id <connection-id> --source-id <source-id>`: Add a source to a connection
- `ormus connection remove-source --project-id <project-id> --connection-id <connection-id> --source-id <source-id>`: Remove a source to a connection
- `ormus connection add-destination --project-id <project-id> --connection-id <connection-id> --destination-id <destination-id>`: Add a destination to a connection
- `ormus connection remove-destination --project-id <project-id> --connection-id <connection-id> --destination-id <destination-id>`: Remove a destination to a connection
- `ormus connection list-sources --project-id <project-id> --connection-id <connection-id>`: List sources of a connection
- `ormus connection list-destinations --project-id <project-id> --connection-id <connection-id>`: List destinations of a connection

### 6. **Event and Data Management**
- **Event Processing and Management**
- `ormus event send --project-id <project-id> --source-id <source-id> --payload <payload> --meta <meta>`: Send event to given source.
- `ormus event get --project-id <project-id> --event-id <event-id>`: Get event.
- `ormus event metrics --project-id <project-id> --connection-id <connection-id> `: Display metrics for given connection.

- **Event Filters**
- `ormus event add-filter --connection-id <connection-id> --filter-id <filter-id>`: Add filter to a connection.
- `ormus event remove-filter --connection-id <connection-id> --filter-id <filter-id>`: Remove filter from a connection.
- `ormus event list-filters --connection-id <connection-id> --filter-id <filter-id>`: List filters for a connection.

### 7. **System-Wide Commands**
- **Configuration and Settings**
- `ormus config set --key <key> --value <value>`: Set a configuration setting.
- `ormus config get --key <key>`: Get a specific configuration setting.
- `ormus config list`: List all configuration settings.

- **Help and Information**
- `ormus help`: Display help information for all commands.
- `ormus <command> --help`: Display help information for a specific command.
- `ormus version`: Display the version of ormus cli.

These commands cover the essential functionalities needed to manage users, projects, sources, destinations, and connections within the Ormus CDP. They provide flexibility for users to perform CRUD operations (Create, Read, Update, Delete) and configure data processing workflows.

Creating a CLI tool with Go involves organizing your project into a clear and maintainable structure. Below is a suggested project structure for the Ormus CLI, along with detailed descriptions of each package and its purpose.

### Project Structure

```
ormus-cli/
|-- cmd/
| |-- ormus/
| |-- main.go
| |-- user.go
| |-- project.go
| |-- source.go
| |-- destination.go
| |-- connection.go
| |-- event.go
| |-- filter.go
| |-- config.go
| |-- root.go
|-- pkg/
| |-- user/
| | |-- user.go
| | |-- service.go
| | |-- repository.go
| |-- project/
| | |-- project.go
| | |-- service.go
| | |-- repository.go
| |-- source/
| | |-- source.go
| | |-- service.go
| | |-- repository.go
| |-- destination/
| | |-- destination.go
| | |-- service.go
| | |-- repository.go
| |-- connection/
| | |-- connection.go
| | |-- service.go
| | |-- repository.go
| |-- event/
| | |-- event.go
| | |-- service.go
| | |-- repository.go
| |-- filter/
| | |-- filter.go
| | |-- service.go
| | |-- repository.go
| |-- config/
| | |-- config.go
| | |-- loader.go
| |-- api/
| | |-- client.go
| | |-- request.go
| |-- util/
| |-- logger.go
| |-- errors.go
|-- internal/
| |-- cli/
| |-- helpers.go
|-- go.mod
|-- go.sum
```

### Detailed Description

#### `cmd/`
- **Purpose**: Contains the entry point and command definitions for the CLI.

1. **`ormus/main.go`**: The main entry point of the CLI application. It initializes the command-line interface and executes the root command.

2. **`ormus/root.go`**: Defines the root command and initializes common configurations (e.g., setting up a global logger or loading configuration files).

3. **`ormus/user.go`**: Implements user-related commands (e.g., `register`, `login`, `logout`, `show`, `update`, `delete`).

4. **`ormus/project.go`**: Implements project-related commands (e.g., `create`, `list`, `show`, `update`, `delete`).

5. **`ormus/source.go`**: Implements source-related commands (e.g., `create`, `list`, `show`, `update`, `delete`).

6. **`ormus/destination.go`**: Implements destination-related commands (e.g., `create`, `list`, `show`, `update`, `delete`).

7. **`ormus/connection.go`**: Implements connection-related commands (e.g., `create`, `list`, `show`, `update`, `delete`).

8. **`ormus/event.go`**: Implements event-related commands (e.g., `create`, `list`, `show`, `update`, `delete`).

9. **`ormus/filter.go`**: Implements filter-related commands (e.g., `create`, `list`, `show`, `update`, `delete`).

10. **`ormus/config.go`**: Manages configuration commands (e.g., `set`, `get`, `list`).

#### `pkg/`
- **Purpose**: Contains the core logic, services, and data access layers for the application.

1. **`user/`**:
- `user.go`: Defines the `User` struct and related methods.
- `service.go`: Contains the business logic for user operations.
- `repository.go`: Provides data access methods for user-related data (could interact with a database or API).

2. **`project/`**:
- `project.go`: Defines the `Project` struct and related methods.
- `service.go`: Contains the business logic for project operations.
- `repository.go`: Provides data access methods for project-related data.

3. **`source/`**:
- `source.go`: Defines the `Source` struct and related methods.
- `service.go`: Contains the business logic for source operations.
- `repository.go`: Provides data access methods for source-related data.

4. **`destination/`**:
- `destination.go`: Defines the `Destination` struct and related methods.
- `service.go`: Contains the business logic for destination operations.
- `repository.go`: Provides data access methods for destination-related data.

5. **`connection/`**:
- `connection.go`: Defines the `Connection` struct and related methods.
- `service.go`: Contains the business logic for connection operations.
- `repository.go`: Provides data access methods for connection-related data.

6. **`event/`**:
- `event.go`: Defines the `Event` struct and related methods.
- `service.go`: Contains the business logic for event operations.
- `repository.go`: Provides data access methods for event-related data.

7. **`filter/`**:
- `filter.go`: Defines the `Filter` struct and related methods.
- `service.go`: Contains the business logic for filter operations.
- `repository.go`: Provides data access methods for filter-related data.

8. **`config/`**:
- `config.go`: Defines the configuration structure.
- `loader.go`: Contains logic for loading and managing configuration files.

9. **`api/`**:
- `client.go`: Manages API client setup and interactions.
- `request.go`: Defines API request logic and helpers.

10. **`util/`**:
- `logger.go`: Provides a common logging mechanism.
- `errors.go`: Defines custom error types and handling utilities.

#### `internal/`
- **Purpose**: Contains internal utilities and helper functions that are not meant to be exposed publicly.

1. **`cli/helpers.go`**: Contains helper functions for CLI operations, such as formatting output, handling user input, and parsing flags.

#### Root Level
- **`go.mod`**: Defines the module and dependencies.
- **`go.sum`**: Contains checksums of the dependencies.

### Notes
- **Dependency Management**: Ensure to use `go mod` for dependency management, which allows for tracking and updating dependencies.
- **Testing**: Each package should have corresponding test files (e.g., `user_test.go`) to ensure the reliability of the code.
- **Documentation**: Keep the code well-documented with comments explaining the purpose of functions, methods, and packages. This is especially important for open-source projects or teams with multiple developers.
- **Security**: Implement proper error handling and security measures, especially when dealing with user data and authentication.

This structure provides a clear separation of concerns, making the project easier to maintain, test, and extend.


One of the most well-known and feature-rich CLI applications written in Go is **[kubectl](https://kubernetes.io/docs/reference/kubectl/overview/)**. `kubectl` is the command-line interface for interacting with Kubernetes clusters, and it exemplifies a well-designed CLI tool with a wide range of functionalities.

### Key Features and Strengths of `kubectl`

1. **Comprehensive Command Structure**:
- `kubectl` has a well-organized and intuitive command structure with commands like `kubectl get`, `kubectl create`, `kubectl delete`, and `kubectl describe`. This structure is both powerful and user-friendly, allowing users to manage complex Kubernetes resources easily.

2. **Extensibility**:
- `kubectl` supports plugins, which allow users to extend its functionality without modifying the core tool. This extensibility makes it possible for users to add custom commands and integrations.

3. **Rich Documentation and Help System**:
- It includes extensive built-in help, accessible via `kubectl help` and `kubectl <command> --help`. The documentation is thorough, making it easier for users to understand and use various commands.

4. **Context Awareness**:
- `kubectl` can operate within different contexts (clusters and namespaces), enabling users to manage multiple Kubernetes environments seamlessly. The `kubectl config` command allows switching contexts easily.

5. **Scripting and Automation**:
- The output of `kubectl` commands can be formatted in various ways (JSON, YAML, wide, name-only), making it suitable for scripting and automation tasks. This flexibility is crucial for integrating with other tools and automating workflows.

6. **Interactive Features**:
- It provides interactive modes, such as `kubectl exec` for executing commands in a container and `kubectl attach` for attaching to a running container.

7. **Security and Authentication**:
- `kubectl` handles authentication and authorization, supporting various methods such as tokens, certificates, and OAuth, ensuring secure interactions with Kubernetes clusters.

8. **Cross-Platform Support**:
- `kubectl` is available on multiple operating systems, including Linux, macOS, and Windows, making it accessible to a broad range of users.

### Other Notable Go-Based CLI Tools

- **[Hugo](https://gohugo.io/)**: A fast and flexible static site generator. It is known for its speed and simplicity, making it popular for building websites quickly.

- **[Goreleaser](https://goreleaser.com/)**: A release automation tool for Go projects, helping developers build, package, and release their projects efficiently.

- **[Cobra](https://github.com/spf13/cobra)**: While not a CLI tool in itself, Cobra is a popular library used to create CLI applications in Go. Many tools, including `kubectl`, are built using Cobra due to its powerful features and ease of use.

- **[Consul CLI](https://www.consul.io/)**: A tool for interacting with Consul, a service networking solution. The Consul CLI provides commands for managing service discovery, configuration, and more.

These tools highlight the versatility and efficiency of Go for building robust, high-performance CLI applications. The Go language's strong concurrency model, efficient standard library, and easy deployment (single static binaries) make it an excellent choice for developing CLIs.

0 comments on commit 5230c60

Please sign in to comment.