# What is Keyshade?

Simple and secure secret management tool for modern developers

## What is Keyshade ?

Keyshade is a secret and configuration manager designed for developers teams and infra. It helps you avoid hardcoding secrets, eliminate sharing your `.env` manually, and keep environment variables in sync—across local setups, CI/CD pipelines, and production. Whether you're solo or working with a team, Keyshade fits into your workflow with minimal setup and maximum security.

## What Can Keyshade Help With ?

Managing secrets sounds simple—until you're juggling .env files, onboarding teammates, and patching leaked tokens. Keyshade helps you solve these problems with a developer-first workflow that’s secure by design.

### Keeping teams and environments in sync

* Environment variables are often scattered across machines, CI pipelines, cloud dashboards, and shared files. It’s hard to know who has the latest version or whether your staging and production configs match.
* **Keyshade keeps everything in one place and lets you sync secrets across environments with a single command.**

### Preventing accidental leaks

* It’s surprisingly easy to commit a secret by mistake. A single hardcoded token can lead to a production incident—or worse.
* **Keyshade scans your codebase for exposed credentials and helps you clean them up before they become a problem.**

### Making secret changes safe and trackable

* Changing secrets manually means if something breaks after a change, it’s hard to trace what happened—or roll back.
* **Keyshade keeps a history of every change, so you can track updates, audit changes, or revert configs when needed.**

### Managing who gets access to what

* Not every team member needs access to every environment or secret. But setting up fine-grained access is usually clunky or not supported at all.
* **Keyshade lets you control access per project, per environment—so devs get what they need, and nothing more.**

### Reducing manual effort

* Changing something as simple as a client ID often means logging into cloud dashboards, restarting servers, or editing configs in multiple places.
* **Keyshade lets you update secrets without restarting your app and automatically pulls fresh values at runtime.**

## Who is Keyshade for ?

Whether you're building solo or deploying with a team, Keyshade takes the pain out of managing secrets.

* **Solo Developers** – Stop copying .env files between machines. Keep everything in sync, securely.
* **Teams** – Share secrets without leaking them. Everyone gets access to what they need—and nothing more.
* **Enterprises** — In a multi-team environment, Keyshade helps you manage secrets and environment variables across teams and projects.
* **CI/CD Pipelines** – Inject secrets at runtime without storing them in plaintext or restarting your app.
* **Security-Minded Projects** – Secrets are encrypted end-to-end and only decrypted on your machine. Even we can't see them.


# Introduction

A walkthrough of how to get started with Keyshade

In this guide, we will take you through the steps required sto set keyshade up and running on your local device, and start using it to manage your secrets and variables.

**But before all that, you would first need to create an account in** [**here**](https://app.keyshade.io)**.**

Here are the topics this guide will be covering. Feel free to skip to any section you like.

* [Installing the CLI](/getting-started/installing-the-cli)
* [Creating a project](/getting-started/creating-a-project)
* [Importing your environment variables](/getting-started/importing-your-environment-variables)
* [Linking your project to keyshade](/getting-started/add-keyshade-to-your-project)
* [Running your app](/getting-started/running-your-app)


# Installing the CLI

A walkthrough of how to install the Keyshade CLI

The Keyshade CLI serves as the entrypoint for your projects and apps to use Keyshade. Currently, our CLI binary is hosted over the npm registry, and it can be installed by running the following command:

## Installation

{% tabs %}
{% tab title="MacOS" %}

```shell
brew tap keyshade-xyz/keyshade https://github.com/keyshade-xyz/keyshade
brew install keyshade
```

{% endtab %}

{% tab title="Windows" %}

```shell
scoop bucket add keyshade https://github.com/keyshade-xyz/keyshade.git
scoop install keyshade
```

{% endtab %}

{% tab title="npm" %}

```shell
npm i -g @keyshade/cli
```

{% endtab %}

{% tab title="pnpm" %}

```shell
pnpm i -g @keyshade/cli
```

{% endtab %}

{% tab title="bun" %}

```shell
bun i -g @keyshade/cli
```

{% endtab %}
{% endtabs %}

That's it! You now have Keyshade installed on your system.

To verify the installation, you can run the following command:

```sh
keyshade --version
```

This should print the version of the Keyshade CLI installed on your system.

![keyshade-cli](/files/EARnMmwVGEjtoWd64WFq)

*(Version shown here is `3.0.1`, but yours may differ depending on installation time or updates.)*

## Authenticate the CLI

Keyshade allows you to perform a secure login directly from your CLI. Once authenticated successfully, you would have your profile configured locally. To begin, run this command:

```shell
keyshade login
```

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FklyYIOuyG5AKyh2FIsOK%2Fuploads%2Fl3JCFYHob9Ojrr6D1rtI%2Flogin.mp4?alt=media&token=78d2fba9-2bc5-4259-973d-0328466fa9d9>" %}

This will ask you for your email—the one that you used earlier to sign up to keyshade, and a deployment URL. In case you are using a self-hosted deployment, you would need to provide the base URL of your API (example - `https://keyshade-api.mydomain.com`). Otherwise, you can skip this step.

Next, enter the sign-in code that you received in your email.

And that's it! You are all set to use the CLI.

## Test your profile

You can run this command to check if your profile is set up correctly:

```shell
keyshade workspace list
```

This command should output a list of all the workspaces that you have access to. If you have just started, there should be only one workspace.


# Creating a project

Get to know about our platform

You would need to create a project to start importing your environment variables to keyshade.

## Creating a new project

Head over to <https://app.keyshade.io>. This is where you get to access our platform. Log in with your email, or your favourite OAuth provider. Once inside, you should be greeted with a similar page like this:

![Dashboard](/files/DGDa03PQ426DIvBU6ZeM)

Now, we can start creating our project.

* Click on **Create Project**
* Enter your project name
* Optionally, you can store the private key in the project **(not recommended in production projects)**
* Edit or add environments if you want to
* Finally, click on **Create Project**
* Download the private and public key then hit on **Close**.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FklyYIOuyG5AKyh2FIsOK%2Fuploads%2Fr1lRLKQ0QgwoeUqmw7dy%2Fcreate%20project.mp4?alt=media&token=fc736e8f-9db5-451c-817d-ce7c619baf09>" %}

Your project should now show up in your dashboard:

![Dashboard](/files/sxiZWEKFHeTgsM1SS9pp)


# Importing your environment variables

Start importing your environment variables into Keyshade

Once your project is set up, the next step is to move your environment variables from `.env` file to Keyshade. There are two ways to do this:

1. Manually creating them one by one
2. Importing the entire `.env` file

We would be sticking with the second option as it is the most convenient way to import your environment variables.

## Import using CLI

1. Head over to your project directory
2. Run the following command:

   ```bash
   keyshade import
   ```
3. Specify the path of the `.env` file
4. Select your default workspace (eg. **My Workspace**)
5. Select the project we created in the previous step
6. Select the environment you want to import the environment variables to (eg. **Development**)
7. Confirm the secret and variable classification
8. Confirm the import

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FklyYIOuyG5AKyh2FIsOK%2Fuploads%2FjafRHirceDhGpaewKmQR%2Fimport%20using%20cli.mp4?alt=media&token=844e42f2-0708-4c5a-a397-d03eeda71ac5>" %}

## Import using the app

1. Head into the project
2. Click on **Import**
3. Select the `.env` file
4. Select the environment you want to import the environment variables to (eg. **Development**)
5. Confirm the secret and variable classification
6. Confirm the import

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FklyYIOuyG5AKyh2FIsOK%2Fuploads%2F0UZn6ujnCQAIJJJNW1lp%2Fimport%20using%20platform.mp4?alt=media&token=20261603-452a-40f1-b2d7-77032bb3153c>" %}

Now, you have your environment variables imported into Keyshade.


# Add Keyshade to your project

Start using keyshade in your project

Initialize keyshade in your local project:

1. Run `keyshade init`

   ```shell
   keyshade init
   ```
2. Select the workspace
3. Select the project
4. Enter the private key that you downloaded after creating the project
5. Select the environment

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FklyYIOuyG5AKyh2FIsOK%2Fuploads%2FwA0awuRV5FEDUgSsgzJe%2Fkeyshade%20init.mp4?alt=media&token=3c717427-9866-48dc-b850-6aa05f2819b2>" %}

Alternatively, you can do all of that in a single command:

```shell
keyshade init --workspace <workspace slug> --project <project slug> --environment <environment slug> --private-key <private key>
```

Once done, it will generate a `keyshade.json` file in your project root. This contains all the information the CLI needs to connect to your keyshade project.

```json
{
  "workspace": "my-workspace-630",
  "project": "my-app-3",
  "environment": "default-223",
  "quitOnDecryptionFailure": false
}
```


# Running your app

Use Keyshade CLI to run your app

Finally, to utilize your environment variables from keyshade in your local project, use this command:

```shell
keyshade run -- <your command>
```

Say you have a NextJS app, you would be using:

```shell
keyshade run -- npm run dev
```

![output](/files/Da3QBOeUv1tqqNoZVebN)

The app has fetched the secret and variable from Keyshade and injected them into the app.

That's it! You have successfully added Keyshade to your project.


# Introduction

A guide on the various entities of Keyshade

This section provides a comprehensive guide to the various entities of Keyshade. Use it as a handbook to navigate the app, understand how the different entities work, and how to use them. Each page describes how to perform various operations using both the app, and the CLI.

Each of the sections presume that you are already authenticated. In case you are following along on web, make sure you are signed in to [app.keyshade.io](https://app.keyshade.io). In case you are following along in CLI, make sure you are logged in using `keyshade login`.


# Workspace

Explainer on what workspaces are and how to use them

## What are Workspaces?

A workspace is what holds all of your data—members, projects, secrets, integrations, etc. You can think of it as an organization, which ties up everything related to a business. You get a default workspace when you first register to keyshade.

A workspace allows you to do the following things:

* Create projects
* Add and manage secrets, variables and environments in these projects
* Create integrations that tie up your external services with keyshade
* Invite and manage members of your organization
* Implement RBAC via roles management
* Upgrade your workspace tier
* Manage billing and subscription

A user can have an unlimited number of workspaces for free.

## Organizing your data

Each workspace is meant to hold data related to a single project, or organization. This means that projects related to a single application or organization should be container in a single workspace.

## The default workspace

When you first register on Keyshade, you get a default workspace. This is where you land when you first log in. The default workspace is meant for personal use, hosting portfolio projects and such. We do not support any payments or subscriptions for the default workspace.

## Supported Functionalities

### Creating a workspace

{% tabs %}
{% tab title="Web" %}

* Head over to the dashboard at [app.keyshade.io](https://app.keyshade.io)
* Navigate to the bottom in the left sidebar and click on the combobox

  ![select combobox](/files/9pwR5QDzL5GMlwAUaDK7)
* Click on **Create a New Workspace**
* Enter the name of the workspace

  ![create workspace dialog](/files/Ifh6rlMeBLxqSb6E2Gx1)
* Click on **Add Workspace**
* And then, you can select your new workspace

  ![created workspace](/files/pgNsgOJIJFlEXXq3bOQ4)
  {% endtab %}

{% tab title="CLI" %}

* Create the workspace

  ```shell
  keyshade workspace create -n <workspace-name>
  ```
* Once done, you can verify that the workspace was created

  ```shell
  keyshade workspace list
  ```

{% endtab %}
{% endtabs %}

### Updating a workspace

{% tabs %}
{% tab title="Web" %}

* From the sidebar, select the workspace that you want to edit
* Click on **Settings**
* Update the information and click on **Save Changes**
  {% endtab %}

{% tab title="CLI" %}

* To update the workspace name, run

  ```shell
  keyshade workspace update <workspace-slug> -n <workspace-name>
  ```

{% endtab %}
{% endtabs %}

### Deleting a workspace

{% tabs %}
{% tab title="Web" %}

* From the sidebar, select the workspace that you want to delete
* Click on **Settings**
* Scroll down, and select "Delete Workspace"
* Enter the name of your workspace to confirm your action
* Click on **Yes, delete the workspace**
  {% endtab %}

{% tab title="CLI" %}

* To update the workspace name, run

  ```shell
  keyshade workspace delete <workspace-slug>
  ```

{% endtab %}
{% endtabs %}


# Environment

Understanding environments in Keyshade - what they are, how they work, and all supported functionalities

## What are Environments?

Environments in Keyshade are **logical containers** that represent different stages or contexts where your application runs. They allow you to manage different configurations for development, staging, production, and any other environments you need.

### Key Characteristics of Environments

* **Logical Separation**: Each environment represents a distinct deployment context
* **Configuration Isolation**: Secrets and variables can have different values per environment
* **Access Control**: Fine-grained permissions control who can access which environments
* **Integration Support**: Environments can be mapped to external deployment platforms
* **Version Management**: Each environment maintains its own version history for configurations

## Why Use Environments?

### Development Workflow Benefits

1. **Environment Isolation**: Keep development, staging, and production configurations separate
2. **Safe Testing**: Test configuration changes in non-production environments first
3. **Team Collaboration**: Different team members can work on different environments
4. **Deployment Flexibility**: Deploy to different environments with appropriate configurations

### Operational Benefits

1. **Configuration Management**: Centralized management of environment-specific settings
2. **Access Control**: Control who has access to sensitive production environments
3. **Audit Trail**: Track changes made to each environment separately
4. **Integration**: Map environments to external platforms (Vercel, AWS, etc.)

## Common Environment Types

### Standard Environments

#### Development

* **Purpose**: Local development and testing
* **Characteristics**: Debug settings, test data, relaxed security
* **Access**: All developers typically have access
* **Example Values**: `LOG_LEVEL=debug`, `DEBUG_MODE=true`

#### Staging

* **Purpose**: Pre-production testing and validation
* **Characteristics**: Production-like settings, test data, moderate security
* **Access**: Limited to QA team and senior developers
* **Example Values**: `LOG_LEVEL=info`, `DEBUG_MODE=false`

#### Production

* **Purpose**: Live application serving real users
* **Characteristics**: Optimized settings, real data, strict security
* **Access**: Restricted to operations team and senior developers
* **Example Values**: `LOG_LEVEL=warn`, `DEBUG_MODE=false`

### Custom Environments

#### Testing

* **Purpose**: Automated testing and CI/CD pipelines
* **Characteristics**: Test-specific configurations, mock services
* **Access**: CI/CD systems and test automation

#### Preview

* **Purpose**: Feature branch deployments and pull request previews
* **Characteristics**: Dynamic configurations, temporary data
* **Access**: Developers and reviewers

#### Demo

* **Purpose**: Client demonstrations and sales presentations
* **Characteristics**: Stable demo data, presentation-optimized settings
* **Access**: Sales team and client-facing roles

## Environment Structure and Fields

### Core Fields

| Field         | Type   | Description                                                  | Required |
| ------------- | ------ | ------------------------------------------------------------ | -------- |
| `name`        | String | The name of the environment (e.g., `development`, `staging`) | Yes      |
| `slug`        | String | URL-friendly identifier (auto-generated from name)           | Auto     |
| `description` | String | Optional description of the environment's purpose            | No       |

### Metadata Fields

| Field             | Type     | Description                               |
| ----------------- | -------- | ----------------------------------------- |
| `id`              | String   | Unique identifier for the environment     |
| `createdAt`       | DateTime | When the environment was created          |
| `updatedAt`       | DateTime | When the environment was last modified    |
| `lastUpdatedById` | String   | Who last updated the environment          |
| `projectId`       | String   | Which project this environment belongs to |

### Relationship Fields

| Field              | Type  | Description                                               |
| ------------------ | ----- | --------------------------------------------------------- |
| `secretVersions`   | Array | Secret versions associated with this environment          |
| `variableVersions` | Array | Variable versions associated with this environment        |
| `integrations`     | Array | External platform integrations mapped to this environment |

## Supported Functionalities

### 1. Creating Environments

Environments can be created through the dashboard interface or via CLI commands. You can create individual environments or use bulk creation for multiple environments at once.

**Key Features:**

* **Individual creation**: Create environments one at a time with custom settings
* **Bulk creation**: Create multiple environments from configuration files
* **Environment templates**: Create environments from predefined templates
* **Custom configurations**: Set up environment-specific settings during creation

For detailed CLI commands, see the [CLI Environment Commands](/cli/environment) documentation.

### 2. Managing Environments

Environment management includes listing, viewing details, and updating environment properties. You can also include configuration details when viewing environments.

**Key Features:**

* **Environment listing**: View all environments in a project with pagination and search
* **Detailed views**: Get comprehensive information about specific environments
* **Configuration inclusion**: View environments with their associated configurations
* **Property updates**: Modify environment names, descriptions, and settings

For detailed CLI commands, see the [CLI Environment Commands](/cli/environment) documentation.

### 3. Environment Access Control

Keyshade provides fine-grained access control for environments, ensuring that only authorized users can view, modify, or delete environment configurations. This is implemented through role-based permissions and workspace-level access controls.

**Permission Levels:**

* **READ\_ENVIRONMENT**: Can view environment details and configurations
* **CREATE\_ENVIRONMENT**: Can create new environments
* **UPDATE\_ENVIRONMENT**: Can modify environment properties
* **DELETE\_ENVIRONMENT**: Can delete environments

**Key Features:**

* **Role-based access**: Assign permissions based on user roles
* **Environment-specific access**: Control access to individual environments
* **Workspace-level control**: Manage access at the workspace level
* **Custom roles**: Create roles with specific permission combinations

For detailed CLI commands, see the [CLI Environment Commands](/cli/environment) documentation.

### 4. Configuration Management

Environment configuration management allows you to set different values for secrets and variables across different environments, apply bulk configurations, and create environment inheritance hierarchies.

**Key Features:**

* **Environment-specific values**: Set different configurations for each environment
* **Bulk configuration**: Apply configurations to multiple environments at once
* **Environment inheritance**: Create environments that inherit from others
* **Configuration templates**: Use predefined configuration templates

For detailed CLI commands, see the [CLI Environment Commands](/cli/environment) documentation.

### 5. Integration Management

Environment integration management allows you to connect environments to external platforms, CI/CD pipelines, and webhook systems for automated deployment and monitoring.

**Key Features:**

* **Platform integrations**: Map environments to external platforms like Vercel, AWS, etc.
* **CI/CD integration**: Connect environments to CI/CD pipelines for automated deployments
* **Webhook integration**: Set up webhooks for environment change notifications
* **Automated deployment**: Automatically deploy configurations to connected platforms

For detailed CLI commands, see the [CLI Environment Commands](/cli/environment) documentation.

### 6. Environment Monitoring

Environment monitoring provides comprehensive visibility into environment health, configuration drift, and audit trails to ensure environments are functioning correctly and securely.

**Key Features:**

* **Configuration drift detection**: Identify differences between environments
* **Health checks**: Monitor environment health and performance
* **Audit logging**: Track all environment changes and access
* **Drift reporting**: Generate detailed reports on configuration differences

For detailed CLI commands, see the [CLI Environment Commands](/cli/environment) documentation.

### 7. Environment Lifecycle Management

Environment lifecycle management includes promoting configurations between environments, cloning environments, and cleaning up unused or old configurations.

**Key Features:**

* **Environment promotion**: Move configurations from one environment to another
* **Environment cloning**: Create copies of environments with all or selective configurations
* **Environment cleanup**: Remove old or unused environment configurations
* **Lifecycle automation**: Automate environment lifecycle processes

For detailed CLI commands, see the [CLI Environment Commands](/cli/environment) documentation.

### 8. Backup and Recovery

Environment backup and recovery provides comprehensive protection for your environment configurations, ensuring you can restore environments from backups and maintain business continuity.

**Key Features:**

* **Environment backup**: Create backups of entire environments or specific configurations
* **Environment restore**: Restore environments from backup files
* **Selective backup**: Backup only specific types of configurations
* **Cross-environment restore**: Restore environments to different environment names

For detailed CLI commands, see the [CLI Environment Commands](/cli/environment) documentation.

## Environment Best Practices

### Naming Conventions

* Use descriptive, consistent names (e.g., `development`, `staging`, `production`)
* Use lowercase with hyphens for multi-word names (e.g., `staging-v2`, `preview-branch`)
* Avoid using sensitive information in environment names

### Environment Organization

* Create environments that match your deployment pipeline
* Use consistent naming across all projects
* Document the purpose of each environment in the description field

### Access Control

* Follow principle of least privilege
* Restrict production environment access to essential personnel only
* Use role-based access control for different environment types
* Regularly audit environment access permissions

### Configuration Management

* Use environment-specific values for all configurations
* Avoid hardcoding environment-specific values in code
* Test configuration changes in non-production environments first
* Document configuration dependencies and relationships

### Security Considerations

* Use different credentials for each environment
* Implement proper access controls for sensitive environments
* Monitor access to production environments
* Regularly rotate credentials in all environments

### Integration Management

* Map environments to external platforms consistently
* Use environment-specific integration configurations
* Monitor integration health and performance
* Document integration dependencies

## Troubleshooting

### Getting Help

* Check the [CLI documentation of Environment Commands](/cli/environment) for command-line usage
* Review [troubleshooting guide](https://github.com/keyshade-xyz/keyshade/blob/main/docs/getting-started/troubleshooting.md)
* Contact support through the dashboard or [GitHub issues](https://github.com/keyshade/keyshade/issues)

## Related Documentation

* [Secrets in Keyshade](https://github.com/keyshade-xyz/keyshade/blob/main/docs/app-reference/secrets.md) - For sensitive configuration values
* [Variables in Keyshade](https://github.com/keyshade-xyz/keyshade/blob/main/docs/app-reference/variables.md) - For non-sensitive configuration values
* [Getting Started Guide](https://github.com/keyshade-xyz/keyshade/blob/main/docs/getting-started/adding-your-first-secret-and-variable.md) - For basic setup


# Secret

Understanding secrets in Keyshade - what they are, how they work, and all supported functionalities

## What are Secrets?

Secrets in Keyshade are **sensitive credentials and authentication data** that need to be protected and managed securely. These include API keys, database passwords, access tokens, private keys, and any other sensitive information that your applications need to function but should never be exposed in plaintext.

### Key Characteristics of Secrets

* **Encrypted at rest**: All secrets are encrypted using public key cryptography before being stored in the database
* **Encrypted in transit**: Secrets are transmitted securely between your application and Keyshade
* **Environment-specific**: Each secret can have different values for different environments (development, staging, production)
* **Versioned**: Every change to a secret creates a new version, allowing you to track history and rollback if needed
* **Access-controlled**: Fine-grained permissions control who can view, modify, or delete secrets
* **Live Updates**: Changes to secrets are automatically propagated to your running applications without restarts
* **Easy Rotation**: Automatically rotate secrets on a schedule or manually when needed

## Common Use Cases

### API Keys and Tokens

* Third-party service API keys (Stripe, AWS, Google Cloud, etc.)
* OAuth access tokens and refresh tokens
* Webhook signing secrets
* Service-to-service authentication tokens

### Database Credentials

* Database connection strings
* Database usernames and passwords
* Connection pool configurations

### Application Secrets

* JWT signing keys
* Session secrets
* Encryption keys
* Private certificates

### Infrastructure Secrets

* SSH private keys
* Cloud provider access keys
* Container registry credentials
* CI/CD pipeline tokens

## Supported Functionalities

### 1. Creating Secrets

A project can house multiple secrets. Here's how you can create one.

{% tabs %}
{% tab title="Web" %}

1. Head over to your [dashboard](https://app.keyshade.io)
2. From the list of projects, select the one under which you would like to create the secret
3. Navigate to the **Secrets** tab
4. Click on the **Create Secret** button
5. Fill in the required fields:
   * **Secret Name**: A unique name for the secret. This should be unique across your project
   * **Extra Note**: An optional description about what the secret holds
   * **Environmental Values**: Set the values for one or more environments for this secret. Different environments are ideally meant to hold different values.
6. Click on the **Add Secret** button
7. You will be redirected to the **Secrets** tab where you can see the list of secrets in your project
   {% endtab %}

{% tab title="CLI" %}

* To create a secret with no values set in the environment, use this command

  ```shell
  keyshade secret create <project_slug> --name <secret_name>
  ```
* To create a secret with values set in the environment, use this command

  ```shell
  keyshade secret create <project_slug> --name <secret_name> -e <environment_slug>=<value>
  ```
* To create a secret with values set in multiple environments, use this command

  ```shell
  keyshade secret create <project_slug> --name <secret_name> -e <environment_slug>=<value> -e <environment_slug>=<value>
  ```
* To verify the secret has been created, use this command

  ```shell
  keyshade secret list <project_slug>
  ```

{% endtab %}
{% endtabs %}

### 2. Updating Secrets

{% tabs %}
{% tab title="Web" %}

1. Head over to the secret you want to edit
2. Click on the **3-dot button** or **right-click** on the secret
3. Select **Edit** from the dropdown menu
4. You can update the name, note, and also the individual environment values for this secret from here
5. Click on the **Save Changes** button once you are done
6. Your updates will be reflected on the secret
   {% endtab %}

{% tab title="CLI" %}

* To update the name of a secret, use this command

  ```shell
  keyshade secret update <secret_slug> --name <secret_name>
  ```
* To update the note of a secret, use this command

  ```shell
  keyshade secret update <secret_slug> --note <note>
  ```
* To update the value of a secret in a specific environment, use this command

  ```shell
  keyshade secret update <secret_slug> -e <environment_slug>=<value>
  ```
* To update the value of a secret in multiple environments, use this command

  ```shell
  keyshade secret update <secret_slug> -e <environment_slug>=<value> -e <environment_slug>=<value>
  ```

{% endtab %}
{% endtabs %}

### 3. Version Management

When you update the environmental value of a secret, it creates a new revisions with your new value. This allows you to revert back to an old value. Here's how you can view and revert to an old value.

{% tabs %}
{% tab title="Web" %}

1. Head over to the secret you want to revert
2. Click on the **3-dot button** or **right-click** on the secret
3. Select **Show Version History** from the dropdown menu
4. Select the revision you want to revert to
5. Click on the **Revert** button
6. Collapse the environment that you want to revert the value of
7. Click on the "clock" button to revert to the selected revision
   {% endtab %}

{% tab title="CLI" %}

* To revert a secret to a specific revision, use this command

  ```shell
  keyshade secret rollback <secret_slug> --environment <environment_slug> --version <revision_number>
  ```

{% endtab %}
{% endtabs %}

### 4. Deleting Secrets

{% tabs %}
{% tab title="Web" %}

1. Head over to the secret you want to delete
2. Click on the **3-dot button** or **right-click** on the secret
3. Select **Delete** from the dropdown menu
4. Confirm the deletion
   {% endtab %}

{% tab title="CLI" %}

* To delete a secret, use this command

  ```shell
  keyshade secret delete <secret_slug>
  ```

{% endtab %}
{% endtabs %}

## Best Practices

### Naming Conventions

* Use descriptive, consistent names (e.g., `DATABASE_PASSWORD`, `STRIPE_SECRET_KEY`)
* Use uppercase with underscores for environment variable compatibility
* Include service or component name in the secret name

### Environment Management

* Use separate environments for different stages (dev, staging, prod)
* Never use production secrets in development
* Regularly rotate secrets in production environments


# Variable

Understanding variables in Keyshade - what they are, how they work, and all supported functionalities

## What are Variables?

Variables in Keyshade are **non-sensitive configuration values** that your applications need to function properly. Unlike secrets, variables are stored in plaintext and are not encrypted, making them suitable for configuration data that doesn't contain sensitive information.

### Key Characteristics of Variables

* **Stored in plaintext**: Variables are not encrypted since they don't contain sensitive data
* **Environment-specific**: Each variable can have different values for different environments
* **Versioned**: Every change to a variable creates a new version for tracking and rollback
* **Access-controlled**: Fine-grained permissions control who can view, modify, or delete variables
* **Fast access**: Since they're not encrypted, variables can be retrieved and updated quickly

## Why Use Variables?

### Configuration Management Benefits

1. **Centralized Configuration**: Store all non-sensitive configuration in one place
2. **Environment Consistency**: Ensure consistent configuration across different environments
3. **Easy Updates**: Change configuration values without code deployments
4. **Team Collaboration**: Share configuration values with team members easily

### Operational Benefits

1. **Live Updates**: Configuration changes are automatically propagated to running applications
2. **Version Control**: Track all configuration changes with full audit trails
3. **Environment Separation**: Different values for development, staging, and production
4. **No Restarts Required**: Update configuration without restarting applications

## Common Use Cases

### Application Configuration

* Port numbers and server settings
* Feature flags and toggles
* Log levels and debugging settings
* Timeout values and retry configurations

### External Service URLs

* API endpoints and base URLs
* Service discovery endpoints
* CDN URLs and asset paths
* Webhook URLs (non-sensitive)

### Environment-Specific Settings

* Database connection timeouts
* Cache TTL values
* Rate limiting configurations
* Monitoring and alerting settings

### Frontend Configuration

* Public API URLs (prefixed with `NEXT_PUBLIC_` for Next.js)
* Build-time configuration
* Feature flags for UI components
* Analytics and tracking IDs

## Variable Structure and Fields

### Core Fields

| Field  | Type   | Description                                          | Required |
| ------ | ------ | ---------------------------------------------------- | -------- |
| `name` | String | The name of the variable (e.g., `PORT`, `LOG_LEVEL`) | Yes      |
| `slug` | String | URL-friendly identifier (auto-generated from name)   | Auto     |
| `note` | String | Optional description or documentation                | No       |

### Versioning Fields

| Field           | Type     | Description                                  |
| --------------- | -------- | -------------------------------------------- |
| `version`       | Integer  | Version number (increments with each change) |
| `value`         | String   | The variable value (stored in plaintext)     |
| `environmentId` | String   | Which environment this version applies to    |
| `createdOn`     | DateTime | When this version was created                |
| `createdById`   | String   | Who created this version                     |

### Metadata Fields

| Field             | Type     | Description                            |
| ----------------- | -------- | -------------------------------------- |
| `createdAt`       | DateTime | When the variable was first created    |
| `updatedAt`       | DateTime | When the variable was last modified    |
| `lastUpdatedById` | String   | Who last updated the variable          |
| `projectId`       | String   | Which project this variable belongs to |

## Supported Functionalities

### 1. Creating Variables

Variables can be created through the dashboard interface or via CLI commands. Each variable can have different values for different environments, allowing you to maintain separate configurations for development, staging, and production.

**Key Features:**

* **Environment-specific values**: Each variable can have different values per environment
* **Bulk creation**: Import multiple variables from configuration files
* **Plaintext storage**: Variables are stored without encryption for fast access
* **Access control**: Set permissions for who can view and modify variables

For detailed CLI commands, see the [CLI Variable Commands](https://github.com/keyshade-xyz/keyshade/blob/main/docs/cli/variable.md) documentation.

### 2. Reading and Retrieving Variables

Variables can be retrieved through various methods depending on your use case. The system supports listing all variables in a project, getting specific variable values, and runtime access for applications.

**Key Features:**

* **Project-wide listing**: View all variables in a project with pagination and search
* **Environment-specific retrieval**: Get variable values for specific environments
* **Runtime access**: Retrieve variables for application use without manual intervention
* **Search and filtering**: Find variables quickly using search terms and filters

For detailed CLI commands, see the [CLI Variable Commands](https://github.com/keyshade-xyz/keyshade/blob/main/docs/cli/variable.md) documentation.

### 3. Updating Variables

Variable updates can include changes to metadata (name, description) or values for specific environments. The system maintains version history for all changes, allowing you to track what was changed and when.

**Key Features:**

* **Metadata updates**: Change variable names and descriptions
* **Value updates**: Update variable values for specific environments
* **Bulk updates**: Update multiple variables from configuration files
* **Version tracking**: All changes create new versions for audit trails

For detailed CLI commands, see the [CLI Variable Commands](https://github.com/keyshade-xyz/keyshade/blob/main/docs/cli/variable.md) documentation.

### 4. Version Management

Every change to a variable creates a new version, providing complete audit trails and rollback capabilities. This ensures you can track who made changes, when they were made, and revert to previous versions if needed.

**Key Features:**

* **Version history**: View all versions of a variable with timestamps and authors
* **Rollback capability**: Revert to any previous version of a variable
* **Version comparison**: Compare different versions to see what changed
* **Audit trails**: Track who made changes and when

For detailed CLI commands, see the [CLI Variable Commands](https://github.com/keyshade-xyz/keyshade/blob/main/docs/cli/variable.md) documentation.

### 5. Environment Management

Variables can be enabled or disabled in specific environments, allowing you to control which environments have access to which variables. This provides fine-grained control over variable availability.

**Key Features:**

* **Environment-specific enable/disable**: Control which environments can access each variable
* **Environment listing**: View which environments have access to specific variables
* **Selective deployment**: Deploy variables only to environments that need them
* **Access control**: Restrict variable access based on environment requirements

For detailed CLI commands, see the [CLI Variable Commands](https://github.com/keyshade-xyz/keyshade/blob/main/docs/cli/variable.md) documentation.

### 6. Access Control and Permissions

Keyshade provides fine-grained access control for variables, ensuring that only authorized users can view, modify, or delete configuration values. This is implemented through role-based permissions and workspace-level access controls.

**Permission Levels:**

* **READ\_VARIABLE**: Can view variable metadata and values
* **CREATE\_VARIABLE**: Can create new variables
* **UPDATE\_VARIABLE**: Can modify existing variables
* **DELETE\_VARIABLE**: Can delete variables

**Key Features:**

* **Role-based access**: Assign permissions based on user roles
* **Workspace-level control**: Manage access at the workspace level
* **Custom roles**: Create roles with specific permission combinations
* **Team collaboration**: Share variables with team members

For detailed CLI commands, see the [CLI Variable Commands](https://github.com/keyshade-xyz/keyshade/blob/main/docs/cli/variable.md) documentation.

### 7. Integration Features

Keyshade provides various integration options to seamlessly incorporate variables into your development workflow and deployment pipelines.

**Key Features:**

* **Webhook notifications**: Get notified when variables change
* **API access**: Programmatic access to variables via API tokens
* **CLI integration**: Use variables directly in your applications
* **CI/CD integration**: Automatically inject variables into deployment pipelines

For detailed CLI commands, see the [CLI Variable Commands](https://github.com/keyshade-xyz/keyshade/blob/main/docs/cli/variable.md) documentation.

### 8. Backup and Recovery

Keyshade provides comprehensive backup and recovery capabilities to ensure your variables are always available and protected against data loss.

**Key Features:**

* **Export functionality**: Export all variables from a project in various formats
* **Import capabilities**: Restore variables from backup files
* **Disaster recovery**: Automatic backups and point-in-time recovery
* **High availability**: Cross-region replication for business continuity

For detailed CLI commands, see the [CLI Variable Commands](https://github.com/keyshade-xyz/keyshade/blob/main/docs/cli/variable.md) documentation.

## Best Practices

### Naming Conventions

* Use descriptive, consistent names (e.g., `PORT`, `LOG_LEVEL`, `API_BASE_URL`)
* Use uppercase with underscores for environment variable compatibility
* Include service or component name in the variable name when needed

### Environment Management

* Use separate environments for different stages (dev, staging, prod)
* Use appropriate values for each environment
* Document the purpose of each variable in the note field

### Access Control

* Follow principle of least privilege
* Use role-based access control
* Regularly audit who has access to what variables
* Remove access for team members who no longer need it

### Configuration Management

* Group related variables logically
* Use consistent naming patterns
* Document variable dependencies and relationships
* Test configuration changes in non-production environments first

### Security Considerations

* Never store sensitive data in variables (use secrets instead)
* Be careful with URLs that might contain sensitive information
* Regularly review variable values for accidental sensitive data
* Use environment-specific values to avoid exposing internal URLs

## Troubleshooting

### Getting Help

* Check the [CLI documentation of Variable Commands](https://github.com/keyshade-xyz/keyshade/blob/main/docs/cli/variable.md) for command-line usage
* Review the [getting started guide](https://github.com/keyshade-xyz/keyshade/blob/main/docs/getting-started/adding-your-first-secret-and-variable.md) for basic troubleshooting
* Contact support through the dashboard or [GitHub issues](https://github.com/keyshade/keyshade/issues)

## Related Documentation

* [Secrets in Keyshade](https://github.com/keyshade-xyz/keyshade/blob/main/docs/app-reference/secrets.md) - For sensitive configuration values
* [Environments in Keyshade](https://github.com/keyshade-xyz/keyshade/blob/main/docs/app-reference/environments.md) - For understanding environment management
* [Getting Started Guide](https://github.com/keyshade-xyz/keyshade/blob/main/docs/getting-started/adding-your-first-secret-and-variable.md) - For basic setup


# Introduction

Get up and running with our CLI tool in no time.

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](/cli/profile): This command is used to create, delete, list and switch between profiles.
* [init](/cli/init): This command is used to initialize your project to tap into the live updates from our platform.
* [run](/cli/run): This command is used to run your application.

## Installing the CLI

To install the CLI, simply run:

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

Verify the installation using:

```bash
keyshade --help
```

## 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.io`.


# Profile

The \`profile\` command

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.io`.

#### `--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.


# Reset

The \`reset\` command

The `reset` command clears the local Keyshade CLI profile cache. It overwrites the files stored under `~/.keyshade/default-profile.json` and `~/.keyshade/profiles.json` with empty JSON objects without modifying workspace or server-side data.

## Usage

```bash
keyshade reset [options]
```

Run the command interactively to confirm you want to wipe the local profiles:

```bash
keyshade reset
```

You can script it (for CI/CD) by skipping the confirmation prompt:

```bash
keyshade reset --yes
```

## Options

#### `-y, --yes`

Skip the confirmation prompt. Useful for non-interactive environments.

#### `-d, --dry-run`

Show which files would be reset without writing any changes.

## Notes

* The reset only affects files in your local home directory.
* The JSON files are recreated with file permissions set to `0600` if they do not already exist.
* If you do not pass `--yes`, the CLI uses an interactive prompt to confirm the reset before proceeding.


# Init

The \`init\` command

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`.


# Workspace

The \`workspace\` command

The `workspace` command is used to manage workspaces on Keyshade. A workspace is a collection of projects, environments, secrets, variables, and roles. It has a set of subcommands:

* [`create`](#create): This command is used to create a new workspace.
* [`delete`](#delete): This command is used to delete an existing workspace.
* [`export`](#export): This command is used to export all projects, environments, secrets, variables, and roles of a workspace into JSON format.
* [`get`](#get): This command is used to fetch a particular workspace.
* [`list`](#list): This command is used to fetch all the workspaces you have access to.
* [`search`](#search): This command is used to perform a full-text search for projects, secrets, variables, and environments in a workspace.
* [`update`](#update): This command is used to update an existing workspace.

## Usage

```bash
keyshade workspace <subcommand> [options]
```

## `create`

### Usage

```bash
keyshade workspace create [options]
```

### Options

These are the options supported by the `create` command:

#### `-n, --name <name>`

The name of the workspace. This is a required field.\
If the name is not provided via the command line option, the user will be prompted to enter it interactively.

#### `-i, --icon <icon>`

The icon to be used for this workspace (optional).

## `delete`

### Usage

```bash
keyshade workspace delete <workspace slug>
```

### Arguments

These are the arguments supported by the `delete` command:

#### `<workspace slug>`

Slug of the workspace which you want to delete.

### Options

The following option is supported by the `delete` command:

#### `-n, --no-confirm`

If provided, skips the interactive confirmation prompt before deleting the workspace. Use with caution as when this option is used, the workspace and all its data will be deleted immediately without any confirmation.

## `export`

### Usage

```bash
keyshade workspace export <workspace slug> [options]
```

### Arguments

These are the arguments supported by the `export` command:

#### `<workspace slug>`

Slug of the workspace which you want to export.

### Options

These are the options supported by the `export` command:

#### `-s, --save-to-file <file>`

Saves the exported data to a file. If not provided, the data will be printed to the console.

## `get`

### Usage

```bash
keyshade workspace get <workspace slug>
```

### Arguments

These are the arguments supported by the `get` command:

#### `<workspace slug>`

The slug of the workspace you want to fetch.

## `list`

### Usage

```bash
keyshade workspace list [options]
```

### Options

These are the options supported by the `list` command:

#### `-p, --page <int>`

Index of the page.

#### `-l, --limit <int>`

Total number of items per page.

#### `-o, --order <string>`

Order to sort by - either ascending (ASC) or descending (DESC).

#### `--sort, --sort <string>`

Field to sort by.

#### `-s, --search <string>`

Search term.

## `search`

### Usage

```bash
keyshade workspace search <workspace slug> <search term>
```

### Arguments

These are the arguments supported by the `search` command:

#### `<workspace slug>`

Slug of the workspace which you want to search for.

#### `<search term>`

The search term you want to use for searching.

## `update`

### Usage

```bash
keyshade workspace update <workspace slug> [options]
```

### Arguments

These are the arguments supported by the `update` command:

#### `<workspace slug>`

The slug of the workspace you want to update.

### Options

These are the options supported by the `update` command:

#### `-n, --name <name>`

The new name for the workspace.

#### `-i, --icon <icon>`

The new icon for the workspace.

At least one of the options (name or icon) must be provided to perform an update.


# Project

The \`project\` command

The `project` command is used to manage projects within a workspace in Keyshade. It provides various subcommands to perform different operations on projects.

## Usage

```bash
keyshade project <subcommand> [options]
```

## Subcommands

The `project` command includes the following subcommands:

* [`create`](#create): Create a new project.
* [`delete`](#delete): Delete an existing project.
* [`fork`](#fork): Fork an existing project.
* [`get`](#get): Get details of a specific project.
* [`list-forks`](#list-forks): List all forks of a project.
* [`list`](#list): List all projects in a workspace.
* [`sync`](#sync): Synchronize a project with its parent.
* [`unlink`](#unlink): Unlink a project from its parent.
* [`update`](#update): Update the properties of an existing project.

## `create`

### Usage

```bash
keyshade project create <workspace-slug> [options]
```

### Arguments

These are the arguments supported by the create command:

#### `<workspace-slug>`

The slug of the workspace under which you want to create the project.

### Options

These are the options supported by the `create` command:

#### `-n, --name <string>`

The name of the project.

#### `-d, --description <string>`

Description of the project. Defaults to project name.

#### `-k, --store-private-key`

Store the private key in the project. Defaults to true.

#### `-a, --access-level <string>`

Access level of the project. Defaults to PRIVATE. Choices are GLOBAL, PRIVATE, INTERNAL.

## `delete`

### Usage

```bash
keyshade project delete <project-slug> [options]
```

### Arguments

These are the arguments supported by the `delete` command:

#### `<project-slug>`

The slug of the project that you want to delete.

## `fork`

### Usage

```bash
keyshade project fork <project-slug> [options]
```

### Arguments

These are the arguments supported by the fork command:

#### `<project-slug>`

The slug of the project under which you want to fork.

### Options

These are the options supported by the `fork` command:

#### `-n, --name <workspace-name>`

The name of the workspace.

#### `-k, --store-private-key <boolean>`

Store the private key in the project. Defaults to true.

#### `-w, --workspace <string>`

Workspace slug to fork the project in

## `get`

### Usage

```bash
keyshade project get <project-slug> [options]
```

### Arguments

These are the arguments supported by the `get` command:

#### `<project-slug>`

The slug of the project which you want to fetch.

## `list-forks`

### Usage

```bash
keyshade project list-forks <project-slug> [options]
```

### Arguments

These are the arguments supported by the `list-forks` command:

#### `<project-slug>`

The slug of the project whose forks you want to list.

## `list`

### Usage

```bash
keyshade project list <workspace-slug> [options]
```

### Arguments

These are the arguments supported by the `list` command:

#### `<workspace-slug>`

The slug of the workspace whose projects you want.

## `sync`

### Usage

```bash
keyshade project sync <project-slug> [options]
```

### Arguments

These are the arguments supported by the sync command:

#### `<project-slug>`

The slug of the forked project that you want to sync with its parent.

### Options

These are the options supported by the `sync` command:

#### `-h, --hard-sync`

Force the child to match the parent by discarding all changes in the child. Defaults to soft sync.

## `unlink`

### Usage

```bash
keyshade project unlink <project-slug> [options]
```

### Arguments

These are the arguments supported by the unlink command:

#### `<project-slug>`

The slug of the forked project that you want to unlink from its parent.

## `update`

### Usage

```bash
keyshade project update <project-slug> [options]
```

### Arguments

These are the arguments supported by the update command:

#### `<project-slug>`

The slug of the project that you want to update.

### Options

These are the options supported by the `update` command:

#### `-n, --name <string>`

The name of the project.

#### `-d, --description <string>`

Description of the project. Defaults to project name.

#### `-k, --store-private-key`

Store the private key in the project. Defaults to true.

#### `-a, --access-level <string>`

Access level of the project. Defaults to PRIVATE. Choices are GLOBAL, PRIVATE, INTERNAL.


# Environment

The \`environment\` command

The `environment` command is used to manage environments in Keyshade. An environment is a context in which secrets and variables are stored and accessed. It has a set of subcommands:

* [`create`](#create): This command is used to create a new environment.
* [`delete`](#delete): This command is used to delete an existing environment.
* [`get`](#get): This command is used to get details of a specific environment.
* [`list`](#list): This command is used to list all environments.
* [`update`](#update): This command is used to update the properties of an existing environment.

## Usage

```bash
keyshade environment <subcommand> [options]
```

## `create`

### Usage

```bash
keyshade environment create <project-slug> [options]
```

### Arguments

These are the arguments supported by the create command:

#### `<project-slug>`

The slug of the project under which you want to add the environment.

### Options

These are the options supported by the `create` command:

#### `-n, --name <string>`

The name of the environment.

#### `-d, --description <string>`

A description of the environment.

## `delete`

### Usage

```bash
keyshade environment delete <environment-id> [options]
```

### Arguments

These are the arguments supported by the delete command:

#### `<environment-id>`

The ID of the environment which you want to delete.

## `get`

### Usage

```bash
keyshade environment get <environment-slug> [options]
```

### Arguments

These are the arguments supported by the get command:

#### `<environment-slug>`

Slug of the environment which you want to fetch.

## `list`

### Usage

```bash
keyshade environment list <project-slug> [options]
```

### Arguments

These are the arguments supported by the list command:

#### `<project-slug>`

Slug of the project whose environments you want.

### Options

These are the options supported by the `list` command:

#### `PAGINATION_OPTION`

The `list` command supports pagination options. These options are defined in the `PAGINATION_OPTION` constant.

## `update`

### Usage

```bash
keyshade environment update <environment-slug> [options]
```

### Arguments

These are the arguments supported by the update command:

#### `<environment-slug>`

Slug of the environment which you want to update.

### Options

These are the options that might be supported by the `update` command:

#### `-n, --name <string>`

The new name for the environment.

#### `-d, --description <string>`

The new description for the environment.


# Run

The \`run\` command

The `run` command is used to run your application with live configuration updates from keyshade. All the secrets and variables are injected into your application as environment variables. This command reads the `keyshade.json` file in your project root by default, but you can override settings using runtime flags.

## 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 `run` command supports the following options for runtime configuration overrides:

* `-e, --environment <slug>`\
  Override the environment at runtime. This allows you to run your application in a different environment without modifying your configuration file.
* `-w, --workspace <slug>`\
  Override the workspace at runtime. Useful when switching between different workspaces for the same project.
* `-p, --project <slug>`\
  Override the project at runtime. Allows connecting to a different project without updating the config file.
* `-f, --config-file <path>`\
  Specify a different configuration file instead of the default `keyshade.json`. Useful for maintaining different configurations for different environments.

### Flag Precedence

The flags follow this precedence order (highest to lowest):

1. **Runtime flags** (`-w`, `-p`, `-e`) - Always take precedence when specified
2. **Custom config file** (`-f`) - Used if no conflicting runtime flags are provided
3. **Default keyshade.json** - Used when no overrides are specified

## Examples

### Basic usage

Run with default `keyshade.json` configuration:

```bash
keyshade run "npm run dev"
```

### Override environment

Run with a different environment:

```bash
keyshade run --environment staging "npm run dev"
```

### Override multiple settings

Connect to a different project and environment:

```bash
keyshade run --project node-app-0 --environment dev-1 "npm start"
```

### Use custom config file

Run with a staging configuration file:

```bash
keyshade run --config-file keyshade.stage.json "npm run dev"
```

### Combine custom config with overrides

Use staging config but override the workspace:

```bash
keyshade run --workspace example-0 --config-file keyshade.stage.json "npm start"
```

## Use Cases

These runtime flags are particularly useful for:

* **CI/CD pipelines**: Different environments can use different configurations without modifying files
* **Multi-environment development**: Quickly switch between development, staging, and production
* **Team collaboration**: Different team members can use the same codebase with their own workspace/project settings
* **Environment-specific deployment**: Deploy to different environments using the same application code

You can also use any global flags with this command.


# Scan

The \`scan\` command

The `scan` command is used to detect any hardcoded secrets in your project files. It can scan specific files, only changed files, or all files in the project.

## Usage

```bash
keyshade scan [options]
```

## Options

These are the options supported by the `scan` command:

### `-f, --file <string>`

Scan a specific file.

Example:

```bash
keyshade scan -f path/to/your/file.js
```

### `-c, --current-changes`

Scan only the current changed files that are not committed.

Example:

```bash
keyshade scan -c
```


# Frameworks

Compiles a list of integration guides to help setting up Keyshade with given frameworks

These guides walk you through integrating and configuring Keyshade with popular frameworks and runtime environments.

## Get started

You can pick up any of these integration guides from the following and start with it.

* [Next.js](/integrations/frameworks/set-up-with-nextjs)
* [Node.js](/integrations/frameworks/set-up-with-nodejs)

Each guide provides step-by-step instructions for setting up Keyshade in your preferred environment, including configuration examples and best practices for secure secret management.


# Next.js

How to set up Keyshade in a Next.js app.

**Keyshade** is a drop-in replacement for `.env` files that manages your secrets and environment variables securely, without needing to commit anything sensitive to your repo.

This guide walks you through integrating Keyshade into your Next.js app step by step.

> Prefer to dive straight into code? Jump to [Running Your App](#run-your-app-with-secure-env-injection)

## Coming Up

Here’s what this guide covers:

* Create a Next.js app
* [Install the Keyshade CLI](/getting-started/installing-the-cli)
* [Set up a profile](broken://pages/MKGEUYGdZThWuYl0fYIl) using your API key
* Create a project and environment in the Keyshade dashboard
* [Add secrets and runtime variables](broken://pages/VVRopxSogrqTIrz0s0m1)
* Link your local project with `keyshade init`
* Run your app with `keyshade run`
* Use `process.env` to access values in both frontend and backend code

> 💡 If you're not familiar with how Keyshade works, we recommend starting with [What is Keyshade?](/getting-started/introduction)

## Create a Next.js Project

If you don't already have a Next.js app, create one using the official CLI:

```bash
npx create-next-app <your-app-name>
```

> Need more options or want to understand what this command does? [Check out the official Next.js documentation](https://nextjs.org/docs/app/api-reference/cli/create-next-app).

## Install the Keyshade CLI

The Keyshade CLI lets you fetch secrets, inject env variables, and manage profiles all from your terminal.

Install it globally:

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

**Note:** Node.js v24 may cause issues with the Keyshade CLI, so use v20 (LTS) for best compatibility.

> See [Installing the CLI](/getting-started/installing-the-cli) for more info.

## Set Up Your Profile

To connect your local environment with Keyshade, create or use a profile.

If this is your **first time using Keyshade**, follow [this guide to set up your profile](broken://pages/MKGEUYGdZThWuYl0fYIl).

If you've already used Keyshade before:

```bash
keyshade profile use <your-profile-name>
```

You can verify which profile is active with:

```bash
keyshade workspace list
```

## Create a Project and Add Secrets

To get started:

1. Go to the [Keyshade Dashboard](https://app.keyshade.io/)
2. Click **“Create Project”**
3. Name your project (e.g. `nextjs-app`)
4. Inside the project, click the **“Secrets”** tab
5. Add your **secrets** (e.g. `NEXT_PUBLIC_API_URL`)
6. Add your **variables** (e.g. `PORT`)

> 💡 **Secrets vs Variables:**
>
> * **Secrets** are sensitive credentials like API keys or tokens. These are encrypted.
> * **Variables** are non-sensitive configs like ports, flags, or feature toggles. These are stored as-is and are not encrypted.

When adding frontend-exposed values, prefix them with `NEXT_PUBLIC_`.

See [Next.js docs](https://nextjs.org/docs/app/guides/environment-variables#bundling-environment-variables-for-the-browser) for details.

> Need help with projects and secrets? See [Managing Secrets & Variables](broken://pages/VVRopxSogrqTIrz0s0m1)

## Initialize Keyshade in Your Project

In order to use the configurations you just created on the dashboard, you would need to initialize Keyshade in your project. This generates the necessary configurations for the CLI to tap into your Keyshade project.

From your project root:

```bash
cd <your-app-name>
```

Run the init command to link your local project with the Keyshade dashboard:

```bash
keyshade init
```

You'll be guided through selecting your workspace, project, and environment.

Want to skip the prompts?

```bash
keyshade init --workspace-slug <my-workspace> --project-slug <my-project> --environment-slug <my-environment> --private-key <my-private-key>
```

This will generate a `keyshade.json` file in your project root.

> More on this in the [CLI Reference](/getting-started/installing-the-cli)

## Run Your App with Secure Env Injection

Start your dev server with Keyshade:

```bash
keyshade run -- npm run dev
```

Example output:

![Next.js Run](/files/Da3QBOeUv1tqqNoZVebN)

Keyshade will inject your secrets and variables securely at runtime.

## Access Secrets and Variables in Your Code

Once your app is running with `keyshade run`, use `process.env` to access any injected values — no extra setup needed.

For example, if you added a secret named or `NEXT_PUBLIC_API_URL` and a variable named `PORT` in the Keyshade dashboard:

```typescript
// Server-side
const port = process.env.PORT;
  
// Client-side
const  apiUrl = process.env.NEXT_PUBLIC_API_URL;
```

### Server-side example

You can access `PORT` inside an API route (say `app/api/hello/route.ts`) like this:

![Server-side example](/files/2lsQP28hQSOt1v1IgVoF)

Now, visit `http://localhost:3000/api/hello` to confirm the port is being read from your Keyshade secret.

![Server-side Output](/files/qet1k4bkCbaGdFtlvD7V)

### Client-side example

Use `NEXT_PUBLIC_API_URL` in your React components at `app/page.tsx`

![Client-side example](/files/udmkfVIhnTYdx9tZehA4)

Now, visit `http://localhost:3000` to see the public API URL rendered in the browser.

![Client-side Output](/files/WJHzOCxCCEa5dI8KzQ95)

**You're All Set 🎊**

*Your Next.js app is now securely powered by Keyshade — no `.env` files, no leaking secrets, and no environment mismatches.*

> Ready to deploy? Check out [Keyshade with Vercel](/integrations/platforms/set-up-with-vercel) for a seamless production setup.


# Node.js

How to set up Keyshade in a Node.js app.

**Keyshade** securely manages your environment variables and secrets — no more `.env` files, and nothing sensitive committed to your repo.

This guide will walk you through setting up Keyshade in a Node.js app, step by step.

> Prefer to dive straight into code? Jump to [Running Your App](#run-your-app-with-secure-env-injection)

## Coming Up

Here's what this guide covers:

* Create a Node.js app
* [Install the Keyshade CLI](/getting-started/installing-the-cli)
* [Set up a profile](broken://pages/MKGEUYGdZThWuYl0fYIl) using your API key
* Create a project and environment in the Keyshade dashboard
* [Add secrets and runtime variables](broken://pages/VVRopxSogrqTIrz0s0m1)
* Link your local project with `keyshade init`
* Run your app with `keyshade run`
* Use `process.env` to access values in your Node.js code

> 💡 New to Keyshade? Start with [What is Keyshade?](/getting-started/introduction) to get a quick overview of how it works.

## Create a Node.js Project

If you don't already have a Node.js app, create one:

```bash
mkdir <your-app-name>
cd <your-app-name>
npm init -y
```

For TypeScript projects, add the necessary dependencies:

```bash
npm install --save-dev typescript @types/node ts-node
npx tsc --init
```

> Need more help with Node.js project setup? [Check out the official Node.js documentation](https://nodejs.org/en/learn/getting-started/introduction-to-nodejs).

## Install the Keyshade CLI

The Keyshade CLI lets you fetch secrets, inject env variables, and manage profiles all from your terminal.

Install it globally:

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

**Note:** Node.js v24 may cause issues with the Keyshade CLI, so use v20 (LTS) for best compatibility.

> See [Installing the CLI](/getting-started/installing-the-cli) for more info.

## Set Up Your Profile

To connect your local environment with Keyshade, create or use a profile.

If this is your **first time using Keyshade**, follow [this guide to set up your profile](broken://pages/MKGEUYGdZThWuYl0fYIl).

If you've already used Keyshade before:

```bash
keyshade profile use <your-profile-name>
```

You can verify which profile is active with:

```bash
keyshade workspace list
```

## Create a Project and Add Secrets

To get started:

1. Go to the [Keyshade Dashboard](https://app.keyshade.io/)
2. Click **"Create Project"**
3. Name your project (e.g. `nodejs-app`)
4. Inside the project, click the **"Secrets"** tab
5. Add your **secrets** (e.g. `API_KEY`, `DATABASE_URL`)
6. Add your **variables** (e.g. `PORT`)

> 💡 **Secrets vs Variables:**
>
> * **Secrets** are sensitive values — like API keys or access tokens — and are encrypted for security.
> * **Variables** are non-sensitive settings — like ports, feature flags, or toggles — and are stored as plain values, not encrypted.

> Need help with projects and secrets? See [Managing Secrets & Variables](broken://pages/VVRopxSogrqTIrz0s0m1)

## Initialize Keyshade in Your Project

In order to use the configurations you just created on the dashboard, you would need to initialize Keyshade in your project. This generates the necessary configurations for the CLI to tap into your Keyshade project.

From your project root:

```bash
cd <your-app-name>
```

Run the init command to link your local project with the Keyshade dashboard:

```bash
keyshade init
```

You'll be guided through selecting your workspace, project, and environment.

Want to skip the prompts?

```bash
keyshade init --workspace-slug <my-workspace> --project-slug <my-project> --environment-slug <my-environment> --private-key <my-private-key>
```

This will generate a `keyshade.json` file in your project root.

> More on this in the [CLI Reference](/getting-started/installing-the-cli)

## Run Your App with Secure Env Injection

Start your Node.js app with Keyshade:

For JavaScript:

```bash
keyshade run -- node index.js
```

For TypeScript:

```bash
keyshade run -- ts-node index.ts
```

Or if you have npm scripts defined in `package.json`:

```bash
keyshade run -- npm start
```

Example output:

![Node.js Run](/files/HK4nmP75IS4pK8mjZ4nd)

Keyshade will inject your secrets and variables securely at runtime.

## Access Secrets and Variables in Your Code

Once your app is running with `keyshade run`, use `process.env` to access any injected values — no extra setup needed.

For example, if you added a secret named `DATABASE_URL` and a variable named `PORT` in the Keyshade dashboard:

In JavaScript:

```javascript
const dbUrl = process.env.DATABASE_URL;
const port = process.env.PORT || 3000;
```

In TypeScript:

```typescript
const dbUrl: string | undefined = process.env.DATABASE_URL;
const port: number = parseInt(process.env.PORT || '3000');
```

### Example Node.js Server

Create a simple Express server in `index.js`:

![Express server in JS](/files/diqdb2GCaP0Zf08vJObi)

Now run it with `keyshade run -- node index.js` and you'll see your server start with all secrets securely injected.

Visit `http://localhost:3000` to confirm your secrets are being injected properly. See below for reference:

![Express Server Output](/files/1hbfqfRT5u2gc6rkw1l5)

**You're All Set 🚀**

*Your Node.js app is now securely powered by Keyshade — no `.env` files, no leaking secrets, and no environment mismatches.*


# Languages

Compiles a list of integration guides to help setting up Keyshade with popular programming languages

These guides walk you through integrating and configuring Keyshade with popular programming languages and runtime environments.

## Get started

You can pick up any of these integration guides from the following and start with it.

* [Go](/integrations/languages/set-up-with-go)
* [Rust](/integrations/languages/set-up-with-rust)
* [Python](/integrations/languages/set-up-with-python)

Each guide provides step-by-step instructions for setting up Keyshade in your preferred language environment, including configuration examples and best practices for secure secret management.


# Go

How to set up Keyshade in a Go app.

**Keyshade** is a drop-in replacement for `.env` files that securely manages your secrets and environment variables. No more accidentally committing your API keys and waking up to unexpected cloud bills.

This guide walks you through integrating Keyshade into your Go application, step by step. Don’t worry, it’s easier than naming your variables without triggering `golint`.

> Prefer to dive straight into code? Jump to [Running Your App](#run-your-app-with-secure-env-injection)

## Coming Up

Here's what this guide covers:

* Create a Go app
* [Install the Keyshade CLI](/getting-started/installing-the-cli)
* [Set up a profile](broken://pages/MKGEUYGdZThWuYl0fYIl) using your API key
* Create a project and environment in the Keyshade dashboard
* [Add secrets and runtime variables](broken://pages/VVRopxSogrqTIrz0s0m1)
* Link your local project with `keyshade init`
* Run your app with `keyshade run`
* Use `os.Getenv` to access values in your Go code

> 💡 If you're not familiar with how Keyshade works, we recommend starting with [What is Keyshade?](/getting-started/introduction)

## Create a Go Project

If you don't already have a Go app, create one with Go modules:

```bash
mkdir <your-app-name>
cd <your-app-name>
go mod init <your-module-name>
```

This creates a `go.mod` file for dependency management.

For web applications, you might want to add common dependencies:

```bash
go get github.com/gin-gonic/gin
go get github.com/gorilla/mux
```

> Need more help with Go project setup? [Check out the official Go documentation](https://golang.org/doc/tutorial/create-module).

## Install the Keyshade CLI

The Keyshade CLI lets you fetch secrets, inject env variables, and manage profiles all from your terminal.

Install it globally:

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

**Note:** Node.js v24 may cause issues with the Keyshade CLI, so use v20 (LTS) for best compatibility.

> See [Installing the CLI](/getting-started/installing-the-cli) for more info.

## Set Up Your Profile

To connect your local environment with Keyshade, create or use a profile.

If this is your **first time using Keyshade**, follow [this guide to set up your profile](broken://pages/MKGEUYGdZThWuYl0fYIl).

If you've already used Keyshade before:

```bash
keyshade profile use <your-profile-name>
```

You can verify which profile is active with:

```bash
keyshade workspace list
```

## Create a Project and Add Secrets

To get started:

1. Go to the [Keyshade Dashboard](https://app.keyshade.io/)
2. Click **"Create Project"**
3. Name your project (e.g. `go-app`)
4. Inside the project, click the **"Secrets"** tab
5. Add your **secrets** (e.g. `DATABASE_URL`)
6. Add your **variables** (e.g. `PORT`)

> 💡 **Secrets vs Variables:**
>
> * **Secrets** are sensitive credentials like API keys or tokens. These are encrypted.
> * **Variables** are non-sensitive configs like ports, flags, or feature toggles. These are stored as-is and are not encrypted.

> Need help with projects and secrets? See [Managing Secrets & Variables](broken://pages/VVRopxSogrqTIrz0s0m1)

## Initialize Keyshade in Your Project

In order to use the configurations you just created on the dashboard, you would need to initialize Keyshade in your project. This generates the necessary configurations for the CLI to tap into your Keyshade project.

From your project root:

```bash
cd <your-app-name>
```

Run the init command to link your local project with the Keyshade dashboard:

```bash
keyshade init
```

You'll be guided through selecting your workspace, project, and environment.

Want to skip the prompts?

```bash
keyshade init --workspace-slug <my-workspace> --project-slug <my-project> --environment-slug <my-environment> --private-key <my-private-key>
```

This will generate a `keyshade.json` file in your project root.

> More on this in the [CLI Reference](/getting-started/installing-the-cli)

## Run Your App with Secure Env Injection

Start your Go app with Keyshade:

```bash
keyshade run -- go run main.go
```

For building and running:

```bash
keyshade run -- go build -o myapp && ./myapp
```

For specific packages:

```bash
keyshade run -- go run ./cmd/server
```

For example:

![GoLang Run](/files/0RIN9ujhMANWlrrAwErt)

Keyshade will inject your secrets and variables securely at runtime.

## Access Secrets and Variables in Your Code

Once your app is running with `keyshade run`, use `os.Getenv` to access any injected values — no extra setup needed.

For example, if you added a secret named `DATABASE_URL` and a variable named `PORT` in the Keyshade dashboard:

```go
dbURL := os.Getenv("DATABASE_URL")
portStr := os.Getenv("PORT")
```

### Example HTTP Server with Gin

Create a web server in `main.go`:

![Example Web Server in Go](/files/HQuHH2pUXqVHvi2n83wV)

Make sure the Gin dependency is added to your project:

```bash
go get github.com/gin-gonic/gin
```

Use `keyshade run -- go run main.go` to start your server with all secrets securely injected.

Visit `http://localhost:8080` to confirm your secrets are being loaded properly.

![Output](/files/J7TczQQVvwQRzKHQ34GI)

**You're All Set 💃**

*Your Go app is now securely powered by Keyshade — no `.env` files, no leaking secrets, and no environment mismatches.*


# Python

How to set up Keyshade in a Python app.

**Keyshade** is a secure, runtime alternative to `.env` files — it keeps your secrets and environment variables safe, without ever needing to commit them to your repo.

This guide walks you through integrating Keyshade into your Python app, step by step — no `import os` gymnastics required.

> Prefer to dive straight into code? Jump to [Running Your App](#run-your-app-with-secure-env-injection)

## Coming Up

Here's what this guide covers:

* Create a Python app
* [Install the Keyshade CLI](/getting-started/installing-the-cli)
* [Set up a profile](broken://pages/MKGEUYGdZThWuYl0fYIl) using your API key
* Create a project and environment in the Keyshade dashboard
* [Add secrets and runtime variables](broken://pages/VVRopxSogrqTIrz0s0m1)
* Link your local project with `keyshade init`
* Run your app with `keyshade run`
* Use `os.environ` to access values in your Python code

> 💡 First time using Keyshade? We recommend starting with [What is Keyshade?](/getting-started/introduction) to get familiar with how it works.

## Create a Python Project

If you don't already have a Python app, create one with a virtual environment:

```bash
mkdir <your-app-name>
cd <your-app-name>
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```

> See the [official Python documentation on venv](https://docs.python.org/3/library/venv.html#how-venv-works) for more details.

## Install the Keyshade CLI

The Keyshade CLI lets you fetch secrets, inject env variables, and manage profiles all from your terminal.

Install it globally:

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

**Note:** Node.js v24 may cause issues with the Keyshade CLI, so use v20 (LTS) for best compatibility.

> See [Installing the CLI](/getting-started/installing-the-cli) for more info.

## Set Up Your Profile

To connect your local environment with Keyshade, create or use a profile.

If this is your **first time using Keyshade**, follow [this guide to set up your profile](broken://pages/MKGEUYGdZThWuYl0fYIl).

If you've already used Keyshade before:

```bash
keyshade profile use <your-profile-name>
```

You can verify which profile is active with:

```bash
keyshade workspace list
```

## Create a Project and Add Secrets

To get started:

1. Go to the [Keyshade Dashboard](https://app.keyshade.io/)
2. Click **"Create Project"**
3. Name your project (e.g. `python-app`)
4. Inside the project, click the **"Secrets"** tab
5. Add your **secrets** (e.g. `API_KEY`, `DATABASE_URL`)
6. Add your **variables** (e.g. `PORT`)

> 💡 **Secrets vs Variables:**
>
> * **Secrets** are sensitive credentials, such as API keys or access tokens. These are securely encrypted by Keyshade to keep them protected.
> * **Variables** are non-sensitive configuration values, like port numbers, feature flags, or environment modes. These are stored in plain text and are not encrypted.

> Need help with projects and secrets? See [Managing Secrets & Variables](broken://pages/VVRopxSogrqTIrz0s0m1)

## Initialize Keyshade in Your Project

In order to use the configurations you just created on the dashboard, you would need to initialize Keyshade in your project. This generates the necessary configurations for the CLI to tap into your Keyshade project.

From your project root:

```bash
cd <your-app-name>
```

Run the init command to link your local project with the Keyshade dashboard:

```bash
keyshade init
```

You'll be guided through selecting your workspace, project, and environment.

Want to skip the prompts?

```bash
keyshade init --workspace-slug <my-workspace> --project-slug <my-project> --environment-slug <my-environment> --private-key <my-private-key>
```

This will generate a `keyshade.json` file in your project root.

> More on this in the [CLI Reference](/getting-started/installing-the-cli)

## Run Your App with Secure Env Injection

Start your Python app with Keyshade:

For a simple Python script:

```bash
keyshade run -- python main.py
```

For web frameworks:

```bash
keyshade run -- flask run
keyshade run -- uvicorn app:app --reload
keyshade run -- python manage.py runserver
```

Example Output:

![Python Run](/files/RzStuB3siULSugSZw16Q)

Keyshade will inject your secrets and variables securely at runtime.

## Access Secrets and Variables in Your Code

Once your app is running with `keyshade run`, use `os.environ` to access any injected values — no extra setup needed.

For example, if you added secrets named `DATABASE_URL` and `API_KEY`, and a variable named `PORT` in the Keyshade dashboard:

```python
db_url = os.environ.get("DATABASE_URL")
port = int(os.environ.get("PORT", 5000))
api_key = os.environ.get("API_KEY")
```

### Example Flask Application

Create a simple Flask app in `app.py`:

![Flask app](/files/isoYd6aUtQ8TyQzPagR8)

Now use `keyshade run -- python app.py` to start your Flask server with all secrets securely injected.

Visit `http://localhost:5000` to confirm your secrets are being loaded properly.

![](/files/W9Qc609tRG97Bf3dWyip)

**You're All Set 🎊**

*Your Python app is now securely powered by Keyshade — no `.env` files, no leaking secrets, and no environment mismatches.*


# Rust

How to set up Keyshade in a Rust app.

**Keyshade** is a secure, runtime alternative to `.env` files — it lets you manage secrets and environment variables safely, without committing anything sensitive to your repo.

This guide walks you through adding Keyshade to your Rust app, step by step — no need to `unwrap()` your secrets from `.env` ever again.

> Prefer to dive straight into code? Jump to [Running Your App](#run-your-app-with-secure-env-injection)

## Coming Up

Here's what this guide covers:

* Create a Rust app
* [Install the Keyshade CLI](/getting-started/installing-the-cli)
* [Set up a profile](broken://pages/MKGEUYGdZThWuYl0fYIl) using your API key
* Create a project and environment in the Keyshade dashboard
* [Add secrets and runtime variables](broken://pages/VVRopxSogrqTIrz0s0m1)
* Link your local project with `keyshade init`
* Run your app with `keyshade run`
* Use `std::env` to access values in your Rust code

> 💡 If you're not familiar with how Keyshade works, we recommend starting with [What is Keyshade?](/getting-started/introduction)

## Create a Rust Project

If you don't already have a Rust app, create one using Cargo:

```bash
cargo new <your-app-name>
cd <your-app-name>
```

This creates a `Cargo.toml` file and a `src/main.rs` file for your new project.

For web applications, you might want to add common dependencies. For example:

```toml
[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
```

> Need more help with Rust project setup? [Check out the official Rust documentation](https://doc.rust-lang.org/cargo/guide/creating-a-new-project.html).

## Install the Keyshade CLI

The Keyshade CLI lets you fetch secrets, inject env variables, and manage profiles all from your terminal.

Install it globally:

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

**Note:** Node.js v24 may cause issues with the Keyshade CLI, so use v20 (LTS) for best compatibility.

> See [Installing the CLI](/getting-started/installing-the-cli) for more info.

## Set Up Your Profile

To connect your local environment with Keyshade, create or use a profile.

If this is your **first time using Keyshade**, follow [this guide to set up your profile](broken://pages/MKGEUYGdZThWuYl0fYIl).

If you've already used Keyshade before:

```bash
keyshade profile use <your-profile-name>
```

You can verify which profile is active with:

```bash
keyshade workspace list
```

## Create a Project and Add Secrets

To get started:

1. Go to the [Keyshade Dashboard](https://app.keyshade.io/)
2. Click **"Create Project"**
3. Name your project
4. Inside the project, click the **"Secrets"** tab
5. Add your **secrets** (e.g. `DATABASE_URL`, `API_KEY`)
6. Add your **variables** (e.g. `PORT`)

> 💡 **Secrets vs Variables:**
>
> * **Secrets** are sensitive credentials like API keys or tokens. These are encrypted.
> * **Variables** are non-sensitive configs like ports, flags, or feature toggles. These are stored as-is and are not encrypted.

> Need help with projects and secrets? See [Managing Secrets & Variables](broken://pages/VVRopxSogrqTIrz0s0m1)

## Initialize Keyshade in Your Project

In order to use the configurations you just created on the dashboard, you would need to initialize Keyshade in your project. This generates the necessary configurations for the CLI to tap into your Keyshade project.

From your project root:

```bash
cd <your-app-name>
```

Run the init command to link your local project with the Keyshade dashboard:

```bash
keyshade init
```

You'll be guided through selecting your workspace, project, and environment.

Want to skip the prompts?

```bash
keyshade init --workspace-slug <my-workspace> --project-slug <my-project> --environment-slug <my-environment> --private-key <my-private-key>
```

This will generate a `keyshade.json` file in your project root.

> More on this in the [CLI Reference](/getting-started/installing-the-cli)

## Run Your App with Secure Env Injection

Start your Rust app with Keyshade:

```bash
keyshade run -- cargo run
```

For release builds:

```bash
keyshade run -- cargo run --release
```

For specific binaries:

```bash
keyshade run -- cargo run --bin my-server
```

Example Output:

![Rust Run](/files/5LKbsb5d8XsF5QVeSru8)

Keyshade will inject your secrets and variables securely at runtime.

## Access Secrets and Variables in Your Code

Once your app is running with `keyshade run`, use `std::env` to access any injected values — no extra setup needed.

For example, if you added secrets named `DATABASE_URL` and `API_KEY`, and a variable named `PORT` in the Keyshade dashboard:

```bash
let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
let api_key = env::var("API_KEY").expect("API_KEY must be set");
let port = env::var("PORT").unwrap_or_else(|_| "8000".to_string());
```

### Example web server in `src/main.rs`:

![Web Server in Rust](/files/uN4zmTcVRDeH4dcHCBjD)

Make sure to add these dependencies to your `Cargo.toml`:

```toml
[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
serde_json = "1.0"
```

Use `keyshade run -- cargo run` to start your server with all secrets securely injected.

Visit `http://localhost:3000` to confirm your secrets are being loaded properly.

![Output](https://github.com/keyshade-xyz/keyshade/blob/main/blob/rust-guide-output.png)

**You're All Set 🥳**

*Your Rust app is now securely powered by Keyshade — no `.env` files, no leaking secrets, and no environment mismatches.*


# Platforms

Compiles a list of integration guides to help setting up Keyshade with popular deployment platforms

These guides walk you through integrating and configuring Keyshade with popular deployment platforms and cloud services.

## Get started

You can pick up any of these integration guides from the following and start with it.

### Deployment Platforms

* [AWS Lambda](https://github.com/keyshade-xyz/keyshade/blob/main/docs/integration/platforms/set-up-with-aws.md)
* [Vercel](/integrations/platforms/set-up-with-vercel)

### Communication Platforms

* [Slack](https://github.com/keyshade-xyz/keyshade/blob/main/docs/integration/platforms/set-up-with-slack.md)
* [Discord](https://github.com/keyshade-xyz/keyshade/blob/main/docs/integration/platforms/set-up-with-discord.md)

Each guide provides step-by-step instructions for setting up Keyshade in your preferred platform environment, including configuration examples and best practices for secure secret management.


# AWS Lambda


# Vercel

How to integrate Keyshade with Vercel

**Keyshade** seamlessly integrates with Vercel to manage your secrets and environment variables securely across all deployment environments, eliminating the need to manually configure environment variables in your Vercel dashboard.

This guide walks you through setting up the Keyshade-Vercel integration step by step.

> Already familiar with Keyshade? Jump to [Setting up the Integration](#create-the-vercel-integration)

## Coming Up

Here's what this guide covers:

* [Deploy your project to Vercel](#deploy-your-project-to-vercel)
* [Create a Keyshade project](#create-a-keyshade-project) with your secrets and variables
* [Set up the Vercel integration](#create-the-vercel-integration) in the Keyshade dashboard
* [Configure Vercel API token and project ID](#gather-vercel-configuration-details)
* [Map Keyshade environments to Vercel environments](#step-4-map-environments)

> 💡 If you're not familiar with how Keyshade works, we recommend starting with [What is Keyshade?](/getting-started/introduction)

## Prerequisites

Before setting up the integration, ensure you have:

* A Vercel account and a deployed project
* A Keyshade account with a workspace
* Your project's source code ready for deployment

## Deploy Your Project to Vercel

First, deploy your project to Vercel **without** adding environment variables during the deployment process.

1. Push your code to a Git repository (GitHub, GitLab, or Bitbucket)
2. Go to [Vercel Dashboard](https://vercel.com/dashboard)
3. Click **"New Project"**
4. Import your Git repository
5. Configure build settings if needed
6. **Important:** Skip adding environment variables during deployment
7. Click **"Deploy"**

> For detailed deployment instructions, check out the [official Vercel deployment documentation](https://vercel.com/docs/deployments/overview).

## Create a Keyshade Project

Before setting up the integration, you need a Keyshade project with your secrets and environment variables.

1. Go to the [Keyshade Dashboard](https://app.keyshade.io/)
2. Click **"Create Project"**
3. Name your project (e.g., `my-vercel-app`)
4. **Note:** You can skip adding secrets and variables during project creation; these can be added after the integration is set up.

> 💡 **Pro Tip:** Create your Keyshade project first, as you'll need to select it during the integration setup.

## Gather Vercel Configuration Details

Before creating the integration, you'll need to collect some information from your Vercel dashboard.

### Get Your Vercel API Token

1. Go to [Vercel Dashboard](https://vercel.com/dashboard)
2. In the upper-right corner of your dashboard, click your profile picture, then select Settings
3. Navigate to **"Tokens"** in the left sidebar
4. Click **"Create Token"**
5. Give your token a name (e.g., `Keyshade Integration`)
6. Choose the appropriate scope (Personal or Team)
7. Set an expiration date
8. Click **"Create"**
9. **Important:** Copy and save the token immediately! You won't be able to see it again

> For more details on API tokens, see the [Vercel API documentation](https://vercel.com/docs/rest-api).

### Find Your Project ID

1. Go to your project in the Vercel dashboard
2. Navigate to **"Settings"** tab
3. In the **"General"** section, you'll find your **Project ID**
4. Copy the Project ID (it starts with `prj_`)

## Create the Vercel Integration

Now you're ready to set up the integration in Keyshade.

### Step 1: Access Integrations

1. Go to your [Keyshade Dashboard](https://app.keyshade.io/)
2. Navigate to **"Integrations"** in the sidebar
3. Select **"Vercel"** from the available integrations

### Step 2: Configure Integration Settings

Fill in the integration details:

**Integration Name**

* Give your integration a descriptive name (e.g., `My App Vercel Integration`)

### Step 3: Configure Integration Settings

**Vercel Configuration**

* **Token:** Paste the Vercel API token you created earlier
* **Project ID:** Enter your Vercel project ID (starts with `prj_`)

### Step 4: Link Keyshade Project

* **Project:** Select the Keyshade project you created earlier
* **Private Key:** If you haven't saved your project's private key in Keyshade, you'll need to provide it here

### Step 5: Map Environments

Map your Keyshade environments to Vercel environments:

**Available Vercel Environments:**

* **Development:** For local development and preview deployments
* **Preview:** For preview deployments (branch deployments)
* **Production:** For production deployments
* **Custom:** For any custom environments you've configured

  > ⚠️ **Note:** Custom environments require a [Vercel Pro or Enterprise plan](https://vercel.com/pricing). If you're on a supported plan, you'll need to manually copy the `environmentId` from your Vercel dashboard.
  >
  > Unlike standard environments (development, preview, production), **Keyshade will prompt you to enter the `environmentId` when selecting a custom environment during integration setup**.
  >
  > Refer to [Vercel’s documentation on custom environments](https://vercel.com/docs/deployments/environments#custom-environments) for guidance on creating and managing them.

**Mapping Examples:**

* Keyshade `development` → Vercel `development`
* Keyshade `staging` → Vercel `preview`
* Keyshade `production` → Vercel `production`

### Step 6: Create Integration

1. Review your configuration
2. Click **"Create Integration"**
3. Wait for the integration to be successfully created

Once the integration is complete, you can **verify that it worked** by visiting your **Vercel project’s Environment Variables** section. You should see a variable named `KS_PRIVATE_KEY`.

> ℹ️ **What is `KS_PRIVATE_KEY`?** This value is automatically injected by Keyshade. It's essential for your app to securely access any protected data managed by Keyshade.

If you don’t see the variable or the integration fails, try restarting the setup and double-checking your environment mappings.

## Add Your Secrets and Variables

> 💡 **Secrets vs Variables:**
>
> * **Secrets** are sensitive credentials like API keys or tokens. These are encrypted at rest.
> * **Variables** are non-sensitive configs like ports, flags, or feature toggles. These are stored as-is.

Now that the integration is set up, add your secrets and environment variables to your Keyshade project.

1. Go to your Keyshade project dashboard
2. Click the **"Secrets"** tab to add your secrets.
3. Click the **"Variables"** tab to add your variables.

> Example Secrets: `DATABASE_PASSWORD`, `API_KEY`, `STRIPE_SECRET_KEY`
>
> Example Variables: `LOG_LEVEL`, `FEATURE_FLAG_ENABLED`, `NEXT_PUBLIC_API_URL`

## Verify the Integration

To confirm the integration is working:

1. Check your Vercel deployment logs for successful environment variable injection
2. Verify that your application can access the environment variables
3. Test your application functionality that depends on the secrets/variables

## Managing the Integration

### Updating Environment Variables

1. Go to your Keyshade project dashboard
2. Update secrets/variables as needed
3. Redeploy your Vercel project to apply changes

### Modifying Environment Mappings

1. Go to **"Integrations"** in Keyshade
2. Find your Vercel integration
3. Right-click and choose **"Edit"** to modify environment mappings
4. Save changes and redeploy

### Removing the Integration

1. Go to **"Integrations"** in Keyshade
2. Find your Vercel integration
3. Right-click and choose **"Delete"** to remove the integration
4. Manually add environment variables in Vercel if needed

## Troubleshooting

### Common Issues

**Integration creation fails:**

* Verify your Vercel API token is valid and has the correct permissions
* Ensure the Project ID is correct and matches your Vercel project
* Check that your Keyshade project exists and you have access to it

**Environment variables not injected:**

* Confirm the integration is active and properly configured
* Verify environment mappings are correct
* Check that secrets/variables are added to the correct Keyshade environment
* Ensure you've redeployed after setting up the integration

**Deployment failures:**

* Review Vercel deployment logs for specific error messages
* Verify that all required environment variables are present in Keyshade
* Check for any syntax errors in your environment variable values

### Reach Out to Us

Still stuck? We’re here to help.

* 📧 Email us at: <support@keyshade.io>
* 💬 Join our community on [Discord](https://discord.com/invite/mV9PsXsjaH)

Don't hesitate to reach out — we're happy to help with setup, debugging, or general questions.

**You're All Set 🎊**

*Your Vercel deployments are now securely powered by Keyshade — no manual environment variable configuration, no secrets in your repository, and seamless environment management across all deployment stages.*

> Using AWS Lambda? Check out our [AWS Lambda Integration Guide](https://github.com/keyshade-xyz/keyshade/blob/main/docs/integration/platforms/set-up-with-aws.md) to securely manage secrets in your serverless functions.


# Summary

Be a part of the keyshade today!

We are an [open-source](https://github.com/keyshade-xyz/keyshade) organization. We solely rely upon the contributions made from the peers of developers out there, and we are really thankful towards them. Even the smallest of contributions (changing the name of a variable, fixing typos) are very much appreciated.

This series of documents aims at setting up and developing Keyshade in your device locally. Start anywhere you feel like!


# Design of our code

Get to know about the core building blocks of our code

## Brief

When it comes to developing for us, we follow very strict norms! From proper indentation to using design patterns, we do an extensive coverage. But this is really difficult for anyone to grasp randomly. So we decided to compile how each of our modules undergo development and the structure they follow.

## Compilation of designs

* [Organization Of Code](/contributing-to-keyshade/design-of-our-code/organization-of-code)
* [API](/contributing-to-keyshade/design-of-our-code/api)
* [Web](/contributing-to-keyshade/design-of-our-code/web)
* [CLI](/contributing-to-keyshade/design-of-our-code/cli)
* [Integrations](/contributing-to-keyshade/design-of-our-code/integrations)


# Organization of code

An insight into how our codebase is organized

In this section, we will discuss how our codebase is organized. We have tried to keep the codebase as modular as possible to make it easier for developers to understand and contribute to the project. Here are the packages, sub-packages, and how they all contribute to the project.

## Packages under `apps` directory

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**](https://github.com/keyshade-xyz/keyshade/tree/develop/apps/api): The main API server that serves the REST API.
* [**web**](https://github.com/keyshade-xyz/keyshade/tree/develop/apps/web): The web application that serves the homepage.
* [**cli**](https://github.com/keyshade-xyz/keyshade/tree/develop/apps/cli): The CLI application that allows users to interact with the API and tap into live updates for their application.
* [**platform**](https://github.com/keyshade-xyz/keyshade/tree/develop/apps/platform): 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**](https://github.com/keyshade-xyz/keyshade/blob/main/packages/eslint-config-custom/README.md): Contains the custom ESLint configuration for the project.
* [**tsconfig**](https://github.com/keyshade-xyz/keyshade/blob/main/packages/tsconfig/README.md): 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.


# API

Design of our API

This document covers how we have developed our API, the stacks, and things you should know before you get started with it!

## Stack

Our API is developed using the following stack:

* **NestJS** as the base
* **Prisma** as the DDL and DML
* **Node Mailer** as the mail agent

## Structure

As per the NestJS convention, our API base is totally modularized, with each module catering to a particular part of our project. The general module structure is as follows:

* **controller**: Stores the APIs that the clients will be interacting with.
* **service**: Holds the business logic
* **misc**: Holds utility functions and classes localized to the particular module
* **dto**: Contains class objects for data intake from the clients
* **types:** Optionally, some modules have a \`\<module\_name>.types.ts\` file that holds the custom types it uses in the module.

## The common module

Just so that we can employ code reusability without much OOP hassle, we have clustered all of our usable components of the backend under the `common` module.

### The `prisma` module

This module deserves special attention since it deals with the data layer. Apart from the usual files, we have two other:

* `schema.prisma`: This contains the data definition
* `migrations`: This folder stores the migrations generated by running the `pnpm run db:generate-migrations` command. These migrations are the state that the current prisma database is in.


# CLI

Design of our CLI

The CLI is what you use to connect your applications to Keyshade to utilize the configurations. Apart from that, you can also use the CLI to manage your configurations, workspace, and other things. In this document, we will cover how we have developed our CLI, talk about the infrastructure, and how you can start contributing to it.

## Stack

We have a very simple stack for our CLI:

* **NodeJS** as the base
* **Commander** as the CLI framework
* **Clack** for interactive prompts

## Structure

We are following the principles of OOP to design a clean and extendible CLI. The current architecture allows us to easily build upon the existing system to add new features.

### Folder structure

* **commands**: Contains the command files that are used by the CLI
* **util**: Contains utility functions that are used across the CLI
* **types**: Contains the types that are used across the CLI

### The `BaseCommand` class

The `BaseCommand` class is the parent class for all the commands that are used by the CLI. It contains common methods that are used by all the commands. You can find it in `src/commands/base.command.ts`. The objects of the subclasses created are primarily tied up in the `COMMANDS` variable in `index.ts`.

#### Methods

It is an abstract class with only two abstract methods:

* `getName`: This method returns the name of the command
* `getDescription`: This method returns the description of the command

The rest of the commands are optional and can be overridden as per the requirement.

#### Creating a new command

Whenever you try to develop a command, you would need to take the following steps:

* Create a new file in the `commands` folder with this name: `<command-name>.command.ts`
* Create a new class in that file with this format: `export class <CommandName>Command extends BaseCommand`
* Implement the abstract methods `getName` and `getDescription` in the class
* Next up, decide on the other fields that you would like to override from the `BaseCommand` class. It is highly recommended to go through the `BaseCommand` class to understand the methods that you can override.
* If you think you will need to create any more subcommands, create a folder with the name of the command in the `commands` folder and follow the same steps as above. Once done, you would need to tie up those commands by overriding the `getSubCommands` function in the parent command.
* Once you have finished working on the commands, you would need to add the command to the `COMMANDS` variable in `index.ts`.

#### The `action` function

This function is at the heart of the CLI. Any and every action performed by the commands are done inside this function. It is recommended to keep the `action` function as clean as possible and move the logic to other `private` functions if needed.

The action function accepts just a single argument with the type `CommandActionData`:

```typescript
export interface CommandActionData {
  options: Record<string, any>
  args: string[]
}
```

The arguments and options used by the command are passed to the `action` function. You can access them using `data.options` and `data.args`.

Consider this command: `ks profile update main --name "New Name"`. In this command, `main` is the argument and `--name "New Name"` is the option. You can access the argument using `data.args[0]` and the option using `data.options.name`. The code implementation will look something like this:

```typescript
// ... snip
public async action({ options, args }: CommandActionData): Promise<void> {
  const profileName = args[0]
  const { name } = options

  // Your logic here
}
// ... snip
```

#### Best practices

* Please ensure that you don't stash too much functionality inside the `action`. Use self-explanatory private function names and move the logic to those functions.
* We use `fetch` for making HTTP requests. Please ensure that you use the HTTP client from `src/http` to make requests.
* Whenever you are creating any HTTP request, please add the API request to the `src/http/<command>.ts` file. This will help in maintaining the codebase and will make it easier for others to understand the code.


# Web

Design of our Web package

The web application is responsible for serving the homepage, providing users with access to its content and functionality, the stacks, and things you should know before you get started with it!

## Stack

* **Next.js** as the framework
* **React** as the frontend library
* **MDX** for Markdown and JSX integration
* **Tailwind CSS** for utility-first styling
* **Framer Motion** for animations
* **Geist** for UI components
* **@tsparticles/engine, @tsparticles/react, @tsparticles/slim** for particle animations
* **Sonner** for notifications
* **TypeScript** for static typing

## Structure

```
├── web
    ├── public
    ├── src
    |      ├── app
    |      ├── components
    |      └── utils
    └── config_files
```

### web

The main directory that contains all parts of the web app.

#### public

Contains static files and assets.

#### src

Contains the source code of the app.

* **app**: Holds the main pages and settings for the app.
* **components**: Reusable pieces used in the app.
* **utils**: Helper tools and functions that support the app.

#### config\_files

Contains configuration files for the app.


# Integrations

How we develop our integrations

Keyshade uses integrations to allow users to tie up their existing infrastructure with our platform. This document covers how we have developed our integrations, allowing you to understand the architecture and develop your own integrations.

## Classification of integrations

Keyshade broadly classifies integrations into two types:

* **Communication-oriented integrations**: These integrations are used to send notifications to the user. For example, sending a Discord notification to the user when a new project is created.
* **Infrastructure-oriented integrations**: These integrations are used to interact with the user's infrastructure. These are triggered whenever the value of a secret or a variable is changed. For example, updating the environment variables in the user's AWS Lambda function.

## Architecture

Our integrations are developed using the following class structure:

![class-diagram](/files/3jvoNvoZW3P0D1NfKtXj)

Our integrations follow the factory pattern for managing and delegating the integrations. The factory pattern allows us to create an instance of the integration based on the type of integration the user wants to use. The factory pattern is implemented in the `IntegrationFactory` class.

### The various classes

Here's a brief overview of the classes used in our integrations:

* [**IntegrationFactory**](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/integration/plugins/factory/integration.factory.ts): This class is responsible for creating an instance of the integration based on the type of integration the user wants to use. You can find all various kinds of `integrationType`s from the [`IntegrationType` enum](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/prisma/schema.prisma#L161).
* [**BaseIntegration**](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/integration/plugins/base.integration.ts): This is the base class for all integrations. It contains the common methods that all integrations should have. Note that two of the methods, `validatePermittedEvents` and `validatePermittedActions` are already implemented and are recommended against overriding. Rest of the three methods needs to be implemented by the child classes. Please refer to the code documentation to understand what each method does.
* [**IntegrationService**](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/integration/service/integration.service.ts): This class is responsible for managing the integrations. It contains methods to create, update, delete, and fetch integrations. The factory method is called from within this class

### The types used

Apart from the classes, we also use a couple of types to manage the integrations. You can find these in [integration.types.ts](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/integration/integration.types.ts). The types are:

* [**IntegrationMetadata**](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/integration/integration.types.ts#L38): The purpose of this interface is to ensure an uniform type for the data that will be stored in the integration's metadata. Ideally, every integration will be using a particular set of metadata that it will use to make API calls on behalf of Keyshade. This interface is to be extended by every integration's metadata, and define the keys that the metadata will have. This will then be validated by the `validateMetadata` method in the `BaseIntegration` class.
* [**IntegrationEventData**](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/integration/integration.types.ts#L17): This interface is used to define the data that will be passed to the integrations when an event is triggered.

## How the flow works

* An event occurs in Keyshade
* The [createEvent](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/common/create-event.ts), which is called whenever an event occurs, tries to gather the integrations that are registered for this particular event. You can refer [this](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/common/create-event.ts#L77) to see how it does that.
* After all the registered integrations for this event are retrieved from the database, we run a for loop to create instances of the integrations and call the `emitEvent` method on them.
* The `emitEvent` function retrieves the authentication and other necessary integration details from the `metadata` parameter. It then crafts a request to the integration's API and sends the `data` parameter to the integration's API.

## Developing your own integrations

To develop your own integrations, you need to follow the following steps:

1. Create a new class that extends the `BaseIntegration` class. You can refer to the [BaseIntegration](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/integration/plugins/base.integration.ts) class to understand what methods you need to implement.
2. Implement the methods that you need to override in your child class. You can refer to the [BaseIntegration](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/integration/plugins/base.integration.ts) class to understand what each method does.
3. Create a new `IntegrationType` in the [IntegrationType enum](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/prisma/schema.prisma#L161) and add it to the enum.
4. Extend `IntegrationMetadata` interface in the [integration.types.ts](https://github.com/keyshade-xyz/keyshade/blob/main/apps/api/src/integration/integration.types.ts) file with your custom integration's metadata interface.
5. Add a case to the switch block in the `IntegrationFactory` class to return an instance of your integration when the `integrationType` is the one you created.
6. You are good to go!


# Prerequisites

Of course, to get started, you will need to have the required components in place. Gladly, there isn't much that needs to be done:

* Make sure you have Git installed and have an account in GitHub
* Have your SMTP credentials ready


# Environment Variables

Get to know the environment you are working with

In order to run our application properly, we will need to set up some environment variables. These variables are used to configure the application and are used to connect to various services like the database, SMTP server, OAuth providers, etc.

The environmental variables are split into two parts: Required and Optional variables. The required variables are necessary for the application to run, while the optional variables, if specified, trigger the initialization of certain services.

## .env.example

Here's the description of the environment variables used in the project. You can find the values for these variables in \`.env.example\`.

### Required

* **DATABASE\_URL**: The URL of the PSQL database to connect to. This is used by the [Prisma Client](https://www.prisma.io/docs/orm/prisma-client) to connect to the database.
* **SMTP\_HOST**: This is used to send out emails from the backend.
* **SMTP\_PORT:** The SMTP port as specified by your SMTP provider.
* **SMTP\_SECURE:** The SMTP security as specified by your SMTP client, By default `false`, for local development/testing. Set to `true` for real SMTP servers which support SSL/TLS e.g. in production.
* **SMTP\_EMAIL\_ADDRESS:** The email address you want to be sending out the emails from.
* **SMTP\_PASSWORD:** The app password for your email account.
* **JWT\_SECRET**: The secret used to sign the JWT tokens. It is insignificant in the development environment.
* **WEB\_FRONTEND\_URL, PLATFORM\_FRONTEND\_URL**: The URLs of the web and platform 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.
* **REDIS\_URL**: The required parameter URL that is used by the API to connect to the Redis instance.
* **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.
* **FROM\_EMAIL**: The display of the email sender title.
* **SERVER\_SECRETS**: This value is used to encrypt sensitive details on the server.

### Optional

* **GITHUB\_CLIENT\_ID, GITHUB\_CLIENT\_SECRET, GITHUB\_CALLBACK\_URL:** These settings can be configured by adding an OAuth app in your GitHub account's developer section. Please note that it's not mandatory, until and unless you want to support GitHub OAuth.
* **GOOGLE\_CLIENT\_ID, GOOGLE\_CLIENT\_SECRET, GOOGLE\_CALLBACK\_URL:** These settings can be configured by adding an OAuth app in your Google account's cloud platform. Please note that it's not mandatory, until and unless you want to support Google OAuth.
* **GITLAB\_CLIENT\_ID, GITLAB\_CLIENT\_SECRET, GITLAB\_CALLBACK\_URL:** These settings can be configured by adding an OAuth app in your GitLab account's application section. Please note that it's not mandatory, until and unless you want to support GitLab OAuth.
* **SENTRY\_ORG**: The organization ID associated with your Sentry account.
* **SENTRY\_API\_ENVIRONMENT, NEXT\_PUBLIC\_SENTRY\_ENVIRONMENT**: The environment in which the app is running. It can be either 'development', 'production', or 'test'. Please note that it's not mandatory, it will default to "production" environment for the sentry configuration.
* **SENTRY\_API\_DSN**: The Data Source Name (DSN) for Sentry API, a platform for monitoring, troubleshooting, and resolving issues in real-time. This is used to configure error tracking in the project.
* **SENTRY\_API\_TRACES\_SAMPLE\_RATE**: The sample rate for collecting transaction traces in Sentry API. It determines the percentage of transactions to capture traces for.
* **SENTRY\_API\_PROFILES\_SAMPLE\_RATE**: The sample rate for collecting performance profiles in Sentry API. It determines the percentage of requests to capture performance profiles for.
* **NEXT\_PUBLIC\_SENTRY\_WEB\_DSN**: The Data Source Name (DSN) for Sentry WEB, a platform for monitoring, troubleshooting, and resolving issues in real-time. This is used to configure error tracking in the project.
* **NEXT\_PUBLIC\_SENTRY\_WEB\_TRACES\_SAMPLE\_RATE**: The sample rate for collecting transaction traces in Sentry WEB. It determines the percentage of transactions to capture traces for.
* **NEXT\_PUBLIC\_SENTRY\_WEB\_PROFILES\_SAMPLE\_RATE**: The sample rate for collecting performance profiles in Sentry WEB. It determines the percentage of requests to capture performance profiles for.
* **NEXT\_PUBLIC\_SENTRY\_PLATFORM\_DSN**: The Data Source Name (DSN) for Sentry PLATFORM, a platform for monitoring, troubleshooting, and resolving issues in real-time. This is used to configure error tracking in the project.
* **NEXT\_PUBLIC\_SENTRY\_PLATFORM\_TRACES\_SAMPLE\_RATE**: The sample rate for collecting transaction traces in Sentry PLATFORM. It determines the percentage of transactions to capture traces for.
* **NEXT\_PUBLIC\_SENTRY\_PLATFORM\_PROFILES\_SAMPLE\_RATE**: The sample rate for collecting performance profiles in Sentry PLATFORM. It determines the percentage of requests to capture performance profiles for.
* **SENTRY\_CLI\_DSN**: The Data Source Name (DSN) for Sentry CLI, a platform for monitoring, troubleshooting, and resolving issues in real-time. This is used to configure error tracking in the project.
* **SENTRY\_CLI\_TRACES\_SAMPLE\_RATE**: The sample rate for collecting transaction traces in Sentry CLI. It determines the percentage of transactions to capture traces for.
* **SENTRY\_CLI\_PROFILES\_SAMPLE\_RATE**: The sample rate for collecting performance profiles in Sentry CLI. It determines the percentage of requests to capture performance profiles for.
* **NEXT\_PUBLIC\_GOOGLE\_ANALYTICS\_MEASUREMENT\_ID**: The measurement ID of the Google Analytics account.


# Setting things up

A tour of how to get the prerequisites done

## Setting up the .env file

Make a copy of the `.env.example` file and rename it to `.env`

```bash
cp .env.example .env
```

Fill in the values for the environment variables in the `.env` file. You can find the values for the variables in the [Environment Variables](/contributing-to-keyshade/environment-variables) section.

## Installing Docker

We tend to use docker for doing the heavy lifting on our behalf. Currently, we use it to set up the integration test environment before you make a commit. To make sure your experience is smooth, consider installing docker from <https://docs.docker.com/engine/install/>

## Node Version

Keyshade works with any active Long-Term Support (LTS) version of Node.js. You can download the current LTS version from the [official Node.js website](https://nodejs.org/en/download).

## Setting up `pnpm`

The project uses `pnpm` as the package manager. To install `pnpm`, run the following command:

```bash
npm install -g pnpm
```

{% hint style="info" %}
For Linux users, in case the above command fails with permission error, try running this:

```bash
sudo npm install -g pnpm
```

{% endhint %}

## Installing the dependencies

To install the dependencies, run the following command:

```bash
pnpm install
```

## Building all the required packages

To make sure all the things work fine, build all these packages by running the following commands:

* Build the secret-scan package:

```bash
pnpm build:secret-scan
```

* Build the schema:

```bash
pnpm build:schema
```

* Build the api-client:

```bash
pnpm build:api-client
```

Or, want to save your precious time? Run all three commands in one go by running this command:

```bash
pnpm build:packages
```

## Installing Turbo

The final step involves installing our monorepo management tool. We have transitioned to using Turbo to streamline our development process. To install Turbo, run the following command:

```bash
npm install turbo --global
```

For more information on how to get started with Turbo, refer to the [official Turbo documentation](https://turbo.build/repo/docs).

## Installing nest CLI

If you plan to work on the API, you would need the **NestJS CLI.** To do this, simply run:

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

## Setting up the development environment

We cluster every dependency that Keyshade will need into our `docker compose` file. So, in order to start developing, you will first need to fire up these dependencies using one single command:

```bash
docker compose up -d
```

This will start the following things in a dockerized environment and then expose the services to your host machine:

1. PostgreSQL: This is the database that Keyshade uses to store all the data.
2. Redis: This is the cache store that Keyshade uses to store the cache data.

Please note that, in order for these steps to work, you will need to ensure that the following ports are free:

* 5432
* 6379
* 9000
* 9001

### Issues regarding PostgreSQL

We have heard quite a few contributors facing a difficult time in getting PSQL to work. If you are facing issues with PostgreSQL, you can try the following:

* Ensure that you don't have a local version of PostgreSQL running on your machine.
* Make sure that you don't have any other docker containers running on the same port.

### Shutting things down

Once you have finished your development, it is recommended to shut down the docker infrastructure using:

```bash
docker compose down
```


# Running things locally

Compiles a list of articles to help running the services locally

This document (and the sub-series) guides you on how you can run and test each of the applications on your local device.

## Run locally

You can pick up any of these topics from the following and start with it.

* [Running the API](/contributing-to-keyshade/running-things-locally/running-the-api)
* [Running the Web](/contributing-to-keyshade/running-things-locally/running-the-web-app)
* [Running the CLI](/contributing-to-keyshade/running-things-locally/running-the-cli)
* [Running the Platform](/contributing-to-keyshade/running-things-locally/running-the-platform)
* [API Testing](/contributing-to-keyshade/running-things-locally/api-testing)


# Running the API

Get to know how you can develop the API!

The API resides in the `apps/api` directory. It is a NestJS project. To run the API locally, do the following:

* Generate the prisma types:

```bash
pnpm run db:generate-types
```

* Deploy the migrations:

```bash
pnpm run db:deploy-migrations
```

* Start the server in development mode:

```bash
pnpm run dev:api
```

* There might be a case when you would like to create a completely fresh copy of the database. In that case, you might use the reset command:

```bash
pnpm run db:reset
```

## Testing your code

We currently perform two kinds of tests: **unit tests** and **integration tests.**

After you make sure that you have added your unit tests, or you have made some changes to the existing functionality, you can run them using:

```bash
pnpm run unit:api
```

After this is complete, you can run end-to-end tests to validate your entire application from start to finish. Use this command:

```bash
pnpm run e2e:api
```

You can also skip these first two commands and perform the unit and e2e tests at the same time with:

```bash
pnpm run test:api
```


# Running the Web

Get to know how you can run the web app!

### Running the Web App

The Web App resides in the `apps/web` directory. It is powered by NextJS and TypeScript. To run the Web App locally, do the following:

* In the project root, run:

```sh
pnpm i
```

Next set up the web app for development with:

```sh
pnpm dev:web
```

* Or cd into `apps/web` and run:

```sh
pnpm dev
```

### Testing your code

We use Jest for testing. Run the tests when unit testing, or mock testing the web app separately from the rest of the project.

* To run tests in the root, use this command:

```sh
pnpm test:web
```

### Viewing the Web App

* You can view the web app by opening the <http://localhost:6969> URL in a browser.


# Running the Platform

Get to know how you can run the platform app!

### Running the Platform

The Platform App resides in the `apps/platform` directory. It is powered by NextJS and TypeScript. To run the Platform App locally, do the following:

* In the project root, run:

```sh
pnpm i
```

Next set up the platform app for development with:

```sh
pnpm dev:platform
```

* Or cd into `apps/platform` and run:

```sh
pnpm dev
```

### Testing your code

We use Jest for testing. Run the tests when unit testing, or mock testing the platform app separately from the rest of the project.

* To run tests in the root, use this command:

```sh
pnpm test:platform
```

### Viewing the Platform App

* You can view the platform app by opening the <http://localhost:3025> URL in a browser.


# Running the CLI

Get to know how you can develop the CLI!

You can get started with developing the CLI using the following steps:

* Start developing the code
* The CLI depends upon 2 internal packages: `@keyshade/api-client` and `@keyshade/secret-scan`. Build these two packages:

  ```bash
  pnpm build:api-client
  pnpm build:secret-scan
  ```
* Run the API:

  ```bash
  docker compose up -d
  pnpm dev:api
  ```
* To make a quick check of the features you have just built, run:

  ```bash
  pnpm dev:cli -- <whatever command goes here>
  ```

Note that, if you make any changes to any of the two packages mentioned above, you would need to rebuild them. Otherwise, the changes would not be reflected in the CLI.


# API Testing

⁸---\
description: API testing using Bruno

***

## API Testing

We use Bruno to test our APIs. All of our endpoints are tested using Bruno and we maintain a detailed documentation of every endpoint in our Bruno collection. You can find it in [here](https://github.com/keyshade-xyz/keyshade/blob/develop/api-collection/README.md).

Although we recommend to use Bruno, you can always import the collections into your favorite tool.

### Getting started

* For starters, make sure you have Bruno installed on your system. If not, you can download it from [here](https://www.usebruno.com/downloads)

![Download Bruno](/files/WfoMjVyuV7s4GUzBtKsl)

* Once you have Bruno installed, open it up.

![Open Bruno](/files/Tsb2ZO5XTjDrzGPlazWI)

* Click on `Import Collection`

![Import Collection](/files/gtcSY36UcmDQUhTDMg24)

* Point to the [`api-collection`](https://github.com/keyshade-xyz/keyshade/blob/develop/api-collection/README.md) folder

![API Collection](/files/VSpcB0U815eFJeWWAig5)

* For every collection in the API, the requests hold one or more examples that you can use to test the API. You can also find the schema of the request itself.

### Making changes to the API

Whenever you make a change to the API that adds / removes / updates one or more requests, you are required to update the corresponding collection in the [api-collection](https://github.com/keyshade-xyz/keyshade/blob/develop/api-collection/README.md) folder. Since the collections are tracked in the branch, we expect you to make all the changes in the same branch which you are working on.


# Docker Support

Instructions on how to build & run each part of Keyshade using docker

This document provides instructions on how to build and run our applications using Docker.

## Prerequisites

* Docker must be installed on your system.

## Available Applications

We have Docker support for the following applications:

1. Web Application
2. API
3. Platform

## Building and Running Applications

### Environment Variables

All applications use environment variables from a `.env` file. Ensure this file is present in your project root directory with the necessary configurations.

### Starting and Stopping Services

For a quick way to start up all containers(Web, API and Platform) you can simply run:

```bash
docker compose up -d
```

To stop and remove all services:

```bash
docker compose down
```

### Web Application

To build the web application:

```bash
pnpm docker:build:web
```

To run the web application:

```bash
pnpm docker:run:web
```

### API

To build the API:

```bash
pnpm docker:build:api
```

To run the API:

```bash
pnpm docker:run:api
```

### Platform

To build the platform:

```bash
pnpm docker:build:platform
```

To run the platform:

```bash
pnpm docker:run:platform
```

## Port Usage

The applications use the following ports by default:

* Web Application: 3000
* API: 4200
* Platform: 3025

Ensure these ports are available on your system. If you need to use different ports, you can modify the port mappings in the `package.json` file locally.

For more detailed information about Docker usage, refer to the official Docker documentation.


# Architecture of Keyshade

Glimpse into the bigger picture

The following few diagrams try to explain the architecture of Keyshade.

### Control Flow

![Control Flow](/files/DHyYTGOdbjjjIBdtSp0q)

### Hierarchical Structure

![Hierarchical Structure](/files/yyiwyTetPKytS0e5ps6G)

### Behind the curtain

#### Projects

![Projects](/files/mOOJcx6zCIDoIc5nxNP3)

#### Creating secrets

![Creating secrets](/files/H3cUrKf6gGsmqfXScPtx)

#### Retrieving secrets

![Retrieving secrets](/files/K26lDKYo9bayg0mQ3VA3)


# How the CLI works

The magic behind the CLI tool.

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). 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) 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
}
```