Corev-CLI

An open-source CLI tool for managing dynamic configuration repositories, with a focus on JSON files, on a per-project basis. It is built to pull, push, diff, list, and revert config files across distributed environments, and is ideal for systems where configurations are dynamic and need to be maintainable, versioned, and auditable. It can be plugged into larger automation pipelines as an upstream source of configuration data.

Prerequisites

Corev-CLI is not a "plug-and-play" tool. It only works if there is an API that follows the API specification.
It uses this API to pull and push config files. Without it, the CLI does nothing.

Installation

npm i -g @corev/cli

Available commands

Corev-CLI provides a small set of core commands to help get things done. Configuration files stored in the configs/ folder for quick and offline access.

| Action | Description | |------------|-------------------------------------------------------------------| | init | Set the API endpoint used by the CLI | | pull | Fetch the latest config for a project | | push | Upload a local config file to the server | | diff | Show differences between two config versions | | list | List all available config versions by filename | | revert | Revert the remote configuration to a previous version | | checkout | Fetch a specific config version for a project and save it locally | | env | Create an environment folder under configs//env/ |

Quick start

1. Initialize once

You can configure the CLI using any of the following options:

a) Run interactively (no flags)

corev init

This will prompt you to choose between using the hosted Corev API or your own custom endpoint. If you select hosted, you will also be asked to enter your API token.

b) Use hosted Corev (corev.host)

corev init --host

This prompts you to enter your Corev Host API endpoint (e.g., https://your-corev-instance.com) and an API secret token.

You can also provide the token inline:

corev init --host --token abc123

c) Use your own API endpoint

corev init --api http://localhost:3000

You may also save a token manually:

corev init --api http://localhost:3000 --token abc123

d) Only set a token (if the API is already configured)

corev init --token abc123

This only saves a new token into .corevrc.json and does not change your current API endpoint.

All configuration is saved to .corevrc.json in your project root.

2. Pull the latest config for a project:

corev pull <project>

3. Push a local config file:

corev push <path>

The <path> argument can be relative or absolute, such as:

corev push configs/[email protected]
corev push ./[email protected]
corev push ~/Desktop/[email protected]

The folder structure (e.g., configs/, ~/Desktop/) can be arbitrary.

4. Diff two config files:

corev diff configs/<project>@<version>.json configs/<project>@<version>.json

5. List versions based on filenames

corev list

6. Revert to an older configuration:

corev revert <project> <version>

7. Checkout a specific configuration version:

corev checkout <project> <version>

8. Create environment folders

corev env <project> <env>

9. Use environment-specific configs

You can pull, push, and revert configs for a specific environment using the --env flag.

Pull a config into an environment folder:

corev pull atlas --env staging

This will save the file to:

configs/atlas/env/staging/atlas@<version>.json

Push a config from an environment folder:

corev push configs/atlas/env/staging/[email protected] --env staging

Revert to a specific version in an environment:

corev revert atlas 1.0.0 --env staging

This allows you to manage parallel configurations per environment (dev, staging, test, etc.) while preserving version control.

API specification

HTTP mapping

Implementers SHOULD provide the endpoints listed below so Corev-CLI can perform pull and push operations correctly.

| HTTP Method | Endpoint URL | Description | |-------------|------------------------------|---------------------------------------------| | GET | /configs/:project/latest | Returns the latest configuration | | GET | /configs/:project/:version | Returns a specific configuration by version | | POST | /configs/:project | Uploads a new or updated configuration |

HTTP headers

In addition to method and endpoint matching, the Corev CLI uses custom headers to indicate the context of the operation:

| Header Name | Example Value | Description | |------------------|-------------------|-----------------------------------------------------------------------------------------------------| | x-corev-action | push / revert | Describes the action type: "push", "revert", etc. | | x-corev-secret | abcdef12345 | Token used for authentication (set via corev init) | | x-corev-env | staging | (Optional) Indicates which environment the operation targets; defaults to "production" if omitted |

These headers MUST be supported by API servers that conform to the Corev specification.
The x-corev-action header helps distinguish between operation intents.
The x-corev-env header enables environment-scoped configurations.

If x-corev-env is not set, the server SHOULD assume the "production" environment by default.

File naming

All configuration files SHOULD follow the naming convention below:

<project>@<version>.json

Example:

configs/[email protected]

JSON schema

Every configuration file SHOULD conform to the JSON schema below, which precisely defines the required structure and fields:

{
	"type": "object",
	"properties": {
		"name": {
			"type": "string"
		},
		"version": {
			"type": "string"
		},
		"config": {
			"type": "object",
			"additionalProperties": true
		}
	},
	"required": [
		"name",
		"version",
		"config"
	],
	"additionalProperties": false
}

API contract (recommended)

Sections 1, 2, 3, 4 and 5 below describe a recommended API contract for compatibility with Corev-CLI. The specification is divided into two main parts: the methods (belonging to the ConfigService interface) and the dictionaries (Configuration and UploadResponse).

1 The getLatestConfig() method

Belongs to the Corev ConfigService conformance class.
Expects a single argument, projectName, which identifies the project. It returns a promise that resolves with a Configuration object containing the latest configuration for that project.

partial interface ConfigService {
  Promise<Configuration> getLatestConfig(DOMString projectName);
};

Behavior:

• When this method is invoked, the implementation MUST retrieve the latest configuration from storage (or memory) and return it as a Configuration object.
• If the project is not found, the promise SHOULD be rejected with an appropriate error.

2 The getSpecificConfig() method

Belongs to the Corev ConfigService conformance class. Expects two arguments:

1. projectName, a DOMString specifying the project
2. version, a DOMString specifying the version to retrieve

partial interface ConfigService {
  Promise<Configuration> getSpecificConfig(DOMString projectName, DOMString version);
};

Behavior:

• When this method is invoked, the implementation MUST retrieve the configuration for the specified project and version from storage (or memory) and return it as a Configuration object.
• If the project or the specific version is not found, the promise SHOULD be rejected with an appropriate error (e.g., HTTP 404).

3 The uploadConfig() method

Belongs to the Corev ConfigService conformance class.
Expects two arguments:

1. projectName, a DOMString specifying the project.
2. config, a Configuration object to be stored or updated.

partial interface ConfigService {
  Promise<UploadResponse> uploadConfig(DOMString projectName, Configuration config);
};

Behavior:

• When this method is invoked, the implementation MUST store or update the configuration for the specified project, then return an UploadResponse indicating success or error.
• If policy doesn’t allow a duplicate or earlier version of a configuration, this method SHOULD reject with a 409 Conflict-like error or return an appropriate error response in the UploadResponse.

4 The Configuration dictionary

Represents the structure of a project configuration object.

dictionary Configuration {
  required DOMString name;      // Project name (e.g., "atlas")
  required DOMString version;   // Version string (e.g., "1.0.0")
  required any config;          // JSON object with configuration data
};

Usage notes:

• name typically matches the project identifier (for example, "atlas").
• version can be any string representing a version (for example, "1.0.0," "2025.04.13-alpha,").
• config is an arbitrary JSON-like structure containing key-value pairs relevant to the configuration.

5 The UploadResponse dictionary

Defines the response returned after a successful (or failed) configuration upload.

dictionary UploadResponse {
  required DOMString status;    // "success" or "error"
  DOMString? message;           // Optional message with details
};

Usage notes:

• status MUST be either "success" or "error".
• message MAY be provided to give further context, such as error details or confirmations.

Testing

Start the mock API:

node tests/mock-api.mjs

Then run CLI commands while targeting http://localhost:3000.

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

Corev-CLI is released under the MIT License.