Kipchak CLI

The Kipchak CLI creates a project and adds drivers and middleware to it. It writes plain code into files your project owns, so the API never depends on it at run time: remove it and nothing changes.

Installation

Projects created from starter 4.2 or later already have it, as a development dependency:

vendor/bin/kipchak list

In an existing project, add it with Composer:

composer require --dev kipchak/cli

To create projects with it, install it globally:

composer global require kipchak/cli

The CLI needs PHP 8.4 or later and works with projects on kipchak/core 3.

kipchak new

kipchak new my-api

Creates a project from the starter, as composer create-project kipchak/starter my-api does, and prints the next steps. --starter-version chooses a starter version. A project created this way is identical to one created with Composer.

kipchak add

kipchak add doctrine

Adds a Kipchak driver or middleware to the project:

1. installs the package with composer require;
2. copies its sample configuration into config/, never over a file that already exists;
3. initialises it in drivers/drivers.php or middlewares/middlewares.php, in the position its documentation requires;
4. lists any settings you must supply, such as API keys.

A driver often needs other Kipchak drivers. The Anthropic driver, for example, uses the HTTP driver. add initialises those too, before the package that needs them, and copies their configuration, so the API works on its first request:

$ kipchak add anthropic
Created config/kipchak.http.php
Created config/kipchak.anthropic.php
Modified drivers/drivers.php
kipchak/driver-http: https://kipchak.dev/docs/driver-http
kipchak/driver-anthropic: https://kipchak.dev/docs/driver-anthropic
Set these before using it:
  config/kipchak.anthropic.php: ANTHROPIC_API_KEY

A driver that is already initialised is left as it is.

Names

doctrine, driver-doctrine and kipchak/driver-doctrine all name the Doctrine driver. A few names are both a driver and a middleware, such as feature-flags and opentelemetry; give those in full, as driver-feature-flags or middleware-feature-flags. Every package is listed on the ecosystem page.

Enterprise packages install the same way, with your project's own Composer credentials for the Enterprise repository.

Where middleware goes

Middleware is placed between the two Error::initialise($app) lines of middlewares/middlewares.php (see Middleware), in the order each package documents. Metering and Quotas, for example, go before the authentication middleware, so that they run after it and see who the caller is. The firewall goes after it, so that it runs first. If the order you have already written cannot satisfy a package, add changes nothing and tells you the line to add by hand.

Each package declares its configuration file, its initialise() line and its order in its own composer.json, under extra.kipchak, so the same information is available to any tool.

Previewing changes

kipchak add doctrine --dry-run

shows every change as a diff and writes nothing. For a package that is not installed yet, a dry run says so and runs no Composer command: its configuration and position are known only once the package is installed.

kipchak project

kipchak project

Shows the project the CLI has found (the nearest directory above the current one whose composer.json requires kipchak/core), its kipchak/core version and its namespaces.

Options and exit codes

Every command accepts --format=json, which writes one JSON document to standard output. add and project also accept --project-dir, to work on a project other than the current directory's. Composer's own output goes to standard error.

kipchak add --format=json returns the changes, messages and settings:

{
    "changes": [
        {"path": "config/kipchak.anthropic.php", "action": "create", "content": "...", "diff": "..."}
    ],
    "messages": ["kipchak/driver-anthropic: https://kipchak.dev/docs/driver-anthropic"],
    "settings": [{"file": "config/kipchak.anthropic.php", "key": "ANTHROPIC_API_KEY"}],
    "written": true
}

Fields are added in later versions but never removed or renamed within a major version.

Source

The CLI is MIT-licensed. Its source is at https://1x.ax/mamluk/kipchak/cli, mirrored to https://github.com/kipchak-dev/cli.