docs(cli): Added usage docs (#330)

docs/SUMMARY.md

@@ -1,7 +1,13 @@
 # Table of contents
 
 - [❔ What is keyshade?](README.md)
-- [🏗️ Architecture of keyshade](architecture-of-keyshade.md)
+
+## CLI
+
+- [Introduction](cli/introduction.md)
+- [Profile](cli/profile.md)
+- [Init](cli/init.md)
+- [Run](cli/run.md)
 
 ## 🥰 CONTRIBUTING TO KEYSHADE
 
@@ -20,3 +26,8 @@
  - [Running the Web](contributing-to-keyshade/running-things-locally/running-the-web.md)
  - [Running the CLI](contributing-to-keyshade/running-things-locally/running-the-cli.md)
  - [API Testing](contributing-to-keyshade/running-things-locally/api-testing.md)
+
+## Internals
+
+- [Architecture of keyshade](internals/architecture-of-keyshade.md)
+- [How the CLI works](internals/how-the-cli-works.md)

docs/cli/init.md

@@ -0,0 +1,37 @@
+---
+description: The `init` command
+---
+
+# `init`
+
+The `init` command is used to initialize your project to tap into the live updates from our platform. This command creates a `keyshade.json` file in your project root. This file contains the following information:
+
+## Usage
+
+```bash
+keyshade init [options]
+```
+
+## Options
+
+These are the commands supported by the `init` command:
+
+### `-w, --workspace <workspace>`
+
+The workspace name whose updates you want to tap into.
+
+### `-p, --project <project>`
+
+The project name whose updates you want to tap into. Note that this project must be under the specified workspace.
+
+### `-e, --environment <environment>`
+
+The environment name whose updates you want to tap into. Note that this environment must be under the specified project.
+
+### `-k, --private-key <key>`
+
+The private key for the project+environment pair. This key is used to decrypt the secrets that are sent to your application.
+
+### `-o, --overwrite`
+
+This flag is used to overwrite the existing `keyshade.json` file in the project root. The default is `false`.

docs/cli/introduction.md

@@ -0,0 +1,31 @@
+---
+description: Get up and running with our CLI tool in no time.
+---
+
+# Introduction
+
+Our CLI is one of the major component of keyshade. The CLI is the entrypoint for your application to tap into the live updates from our platform. Whatever changes you make to your secrets or variables in your project, are reflected automatically in your application. Besides that, it also helps you to interact with the keyshade API.
+
+## Commands
+
+The CLI has the following commands:
+
+- [profile](./profile.md): This command is used to create, delete, list and switch between profiles.
+- [init](./init.md): This command is used to initialize your project to tap into the live updates from our platform.
+- [run](./run.md): This command is used to run your application.
+
+## Global flags
+
+Global flags work with any command in the CLI. The following are the global flags:
+
+### `--profile <profile>`
+
+This flag is used to specify the profile to use. If not specified, the default profile is used. If you specify this flag, the [`--api-key`](#--api-key-key) flag and the [`--base-url`](#--base-url-url) flag are ignored.
+
+### `--api-key <key>`
+
+This flag is used to specify the API key to use. Won't work if the [`--profile`](#--profile-profile) flag is specified.
+
+### `--base-url <url>`
+
+This flag is used to specify the base URL of the API to use. Won't work if the [`--profile`](#--profile-profile) flag is specified. The default is `https://api.keyshade.xyz`.

docs/cli/profile.md

@@ -0,0 +1,127 @@
+---
+description: The `profile` command
+---
+
+# `profile`
+
+The `profile` command is used to manage all the profiles in the CLI. A profile is a collection of configurations that are used to interact with the keyshade API. It has a set of subcommands:
+
+- [`create`](#create): This command is used to create a new profile.
+- [`update`](#update): This command is used to update the properties of an existing profile.
+- [`delete`](#delete): This command is used to delete an existing profile.
+- [`list`](#list): This command is used to list all the profiles.
+- [`use`](#use): This command is used to set a default profile.
+
+## Usage
+
+```bash
+keyshade profile <subcommand> [options]
+```
+
+## `create`
+
+### Usage
+
+```bash
+keyshade profile create [options]
+```
+
+### Options
+
+These are the commands supported by the `create` command:
+
+#### `-n, --name <name>`
+
+The name of the profile. This is a required field.
+
+#### `-a, --api-key <key>`
+
+The API key to use with this profile. This is a required field.
+
+#### `-b, --base-url <url>`
+
+The base URL of the API to use with this profile. The default is `https://api.keyshade.xyz`.
+
+#### `--set-default`
+
+If set, this profile will be set as the default profile. Default is `false`.
+
+## `update`
+
+### Usage
+
+```bash
+keyshade profile update <profile> [options]
+```
+
+### Arguments
+
+These are the arguments supported by the `update` command:
+
+#### `<profile>`
+
+The name of the profile to update.
+
+### Options
+
+These are the commands supported by the `update` command:
+
+#### `-n, --name <name>`
+
+The new name of the profile.
+
+#### `-a, --api-key <key>`
+
+The new API key to use with this profile.
+
+#### `-b, --base-url <url>`
+
+The new base URL of the API to use with this profile.
+
+## `delete`
+
+### Usage
+
+```bash
+keyshade profile delete <profile> [options]
+```
+
+### Arguments
+
+These are the arguments supported by the `delete` command:
+
+#### `<profile>`
+
+The name of the profile to delete.
+
+## `list`
+
+### Usage
+
+```bash
+keyshade profile list [options]
+```
+
+### Options
+
+These are the commands supported by the `list` command:
+
+#### `-v, --verbose`
+
+If set, the output will list out the API keys and base URLs as well. Default is `false`.
+
+## `use`
+
+### Usage
+
+```bash
+keyshade profile use <profile> [options]
+```
+
+### Arguments
+
+These are the arguments supported by the `use` command:
+
+#### `<profile>`
+
+The name of the profile to set as the default profile.

docs/cli/run.md

@@ -0,0 +1,25 @@
+---
+description: The `run` command
+---
+
+# `run`
+
+The `run` command is used to run your application. All the secrets and variables are injected into your application as environment variables. This command reads the `keyshade.json` file in your project root to get the necessary information.
+
+## Usage
+
+```bash
+keyshade run <command> [options]
+```
+
+## Arguments
+
+These are the arguments supported by the `run` command:
+
+### `<command>`
+
+The command to run your application. This command is run in the same shell as the `keyshade run` command.
+
+## Options
+
+The function accepts no local options. However, the global flags can be used with this command.

docs/contributing-to-keyshade/design-of-our-code/organization-of-code.md

@@ -10,15 +10,16 @@ In this section, we will discuss how our codebase is organized. We have tried to
 
 The `apps` directory contains all the applications that are part of the project. Each application is a separate package and has its own `package.json` file. The applications are:
 
-- [**`api`**](../../../apps/api/): The main API server that serves the REST API.
-- [**`web`**](../../../apps/web/): The web application that serves the homepage.
-- [**`platform`**](../../../apps/workspace/): The platform application hosts the UI that allows users to do the actual work.
+- [**api**](../../../apps/api/): The main API server that serves the REST API.
+- [**web**](../../../apps/web/): The web application that serves the homepage.
+- [**cli**](../../../apps/cli/): The CLI application that allows users to interact with the API and tap into live updates for their application.
+- [**platform**](../../../apps/workspace/): The platform application hosts the UI that allows users to do the actual work.
 
 ## Packages under `packages` directory
 
 The `packages` directory contains all the shared packages that are used across the applications. These packages are:
 
-- [**`eslint-config-custom`**](../../../packages/eslint-config-custom/): Contains the custom ESLint configuration for the project.
-- [**`tsconfig`**](../../../packages/tsconfig/): Contains the custom TypeScript configuration for the project.
+- [**eslint-config-custom**](../../../packages/eslint-config-custom/): Contains the custom ESLint configuration for the project.
+- [**tsconfig**](../../../packages/tsconfig/): Contains the custom TypeScript configuration for the project.
 
 Apart from the `package.json` files used in the individual packages, we also have a root level `package.json` file that contains the scripts to run the applications and the shared packages. This file also contains the dependencies that are shared across the applications.

docs/contributing-to-keyshade/environment-variables.md

@@ -27,7 +27,7 @@ Here's the description of the environment variables used in the project. You can
 - **WEB_FRONTEND_URL, WORKSPACE_FRONTEND_URL**: The URLs of the web and workspace frontend respectively. These are used in the emails sometimes and in other spaces of the application too.
 - **API_PORT**: The environmental variable that specifies the port number on which the API server should listen for incoming connections. If not explicitly set, it defaults to port 4200.
 
-- **MINIO_ENDPOINT**: This is the endpoint of the Minio server. Minio is an open-source object storage server. 
+- **MINIO_ENDPOINT**: This is the endpoint of the Minio server. Minio is an open-source object storage server.
 - **MINIO_PORT**: The port on which the Minio server is running.
 - **MINIO_ACCESS_KEY**: The access key to the Minio server.
 - **MINIO_SECRET_KEY**: The secret key to the Minio server.
@@ -37,3 +37,5 @@ Here's the description of the environment variables used in the project. You can
 - **REDIS_PASSWORD**: The optional parameter that is used by the API. This is specified only if the Redis instance is configured to use a password.
 
 - **FEEDBACK_FORWARD_EMAIL**: Feedbacks submitted by the user would be sent to this email address for the concerned authorities to view it. Ideally, in development environment, this would be your personal email address
+
+- **NEXT_PUBLIC_BACKEND_URL**: The URL of the backend server. This is used by the frontend to make API requests to the backend.

docs/architecture-of-keyshade.md → docs/internals/architecture-of-keyshade.md

@@ -8,22 +8,22 @@ The following few diagrams try to explain the architecture of keyshade.
 
 ### Control Flow
 
-![Control Flow](../blob/control-flow.png)
+![Control Flow](../../blob/control-flow.png)
 
 ### Hierarchical Structure
 
-![Hierarchical Structure](../blob/data-hierarchy.png)
+![Hierarchical Structure](../../blob/data-hierarchy.png)
 
 ### Behind the curtain
 
 #### Projects
 
-![Projects](../blob/projects.png)
+![Projects](../../blob/projects.png)
 
 #### Creating secrets
 
-![Creating secrets](../blob/secret-creation.png)
+![Creating secrets](../../blob/secret-creation.png)
 
 #### Retrieving secrets
 
-![Retrieving secrets](../blob/secret-retrieval.png)
+![Retrieving secrets](../../blob/secret-retrieval.png)

docs/internals/how-the-cli-works.md

@@ -0,0 +1,59 @@
+---
+description: The magic behind the CLI tool.
+---
+
+# How the CLI works
+
+When developing the CLI, we ensured that we would prioritize ease of use and simplicity. We had the following goals in mind:
+
+- **Secure by design**: We wanted to ensure that your secrets (API Keys and project private keys) are safe by default.
+- **Easy to interpret and configure**: The configuration files that we use to make the CLI run are readable, lightweight and easy to understand.
+- **Fast and efficient**: We wanted to ensure that the CLI is fast and efficient, so that you can get your work done quickly.
+
+## The three main configuration files
+
+When using our CLI, you would need to configure it first.
+
+### Profile
+
+This includes creating one or more [`profiles`](../cli/profile.md). A profile is a simple object that stores your API Key and the API base URL (Yes! We do give you the option to configure the base URL of the API).
+
+The following is the TypeScript interface for a profile:
+
+```typescript
+interface ProfileConfig {
+ default: string
+ [name: string]: {
+ apiKey: string
+ baseUrl: string
+ }
+}
+```
+
+All of your profiles are stored under `~/.keyshade/profiles.json`. You have the ability to have multiple profiles at once. The `default` key is used to specify the default profile that should be used when no profile is specified.
+
+With this done, you can easily use any command to modify items on the platform.
+
+### Project configuration
+
+If you would like your application to tap into the live updates from our platform, you would need to [`init`](../cli/init.md) your project. This command creates a `keyshade.json` file in your project root. This file contains the following information:
+
+```typescript
+interface ProjectRootConfig {
+ workspace: string
+ project: string
+ environment: string
+}
+```
+
+Note that, you can only tap into updates for any given trio of `project`, `environment` and `workspace`.
+
+### Private Key
+
+Perhaps the most important sensitive data in the entire application, we store the secret in a file named `private-keys.json` file under the `~/.keyshade` directory. This file contains key-value pairs of the project+environment name and the private key.
+
+```typescript
+interface PrivateKeyConfig {
+ [projectEnvironment: string]: string
+}
+```