> ## Documentation Index
> Fetch the complete documentation index at: https://darkterminal.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

> Turso PHP Installer manual references

This page will provide a detailed explanation of how to use `turso-php-installer` and explore the additional features it offers to support development in both local and production environments.

```shell $ turso-php-installer theme={null}
  turso-php-installer  2.0.4

  USAGE:  <command> [options] [arguments]

  install                    Install Turso libSQL Extension for PHP
  uninstall                  Uninstall Turso libSQL Extension for PHP
  update                     Update Turso libSQL Extension for PHP
  version                    Display Turso PHP Installer version

  server:ca-cert-create      Generate CA certificate
  server:ca-cert-delete      Delete a CA certificate from the global store location
  server:ca-cert-list        List all generated CA certificates
  server:ca-cert-show        Show raw CA certificate and private key
  server:ca-peer-cert-create Create a peer certificate
  server:cert-store-get      Get the cert store location
  server:cert-store-set      Set/overwrite global certificate store, to use by the server later. Default is same as {installation_dir}/certs
  server:check               Check server requirement, this will check if python3 pip and cyptography lib are installed

  sqld:env-delete            Delete an environment by name or ID
  sqld:env-edit              Edit an existing environment by ID or name
  sqld:env-list              List all created environments
  sqld:env-new               Create new sqld environment, save for future use.
  sqld:env-show              Show detail of environment
  sqld:open-db               Open database using Turso CLI
  sqld:server-run            Run sqld server based on environment id or name

  token:create               Create libSQL Server Database token for Local Development
  token:delete               Delete a database token
  token:list                 Display all generated database tokens
  token:show                 Show libSQL Server Database token for Local Development

```

## Install

Installs the Turso libSQL Extension for PHP, enabling seamless integration of libSQL with PHP applications.

**Usage:**

```bash theme={null}
install [options]
```

**Options:**

* **`--unstable`**\
  Installs the unstable version of the Turso libSQL extension from the development repository.\
  Example:
  ```bash theme={null}
  install --unstable
  ```

* **`--thread-safe`**\
  Installs the Thread Safe (TS) version of the extension, which is necessary for certain PHP setups.\
  Example:
  ```bash theme={null}
  install --thread-safe
  ```

* **`--php-ini[=PHP-INI]`**\
  Specifies the path to the `php.ini` file to use for configuring the extension.\
  Example:
  ```bash theme={null}
  install --php-ini=/etc/php.ini
  ```

* **`--php-version[=PHP-VERSION]`**\
  Specifies the PHP version to use for the installation.\
  Example:
  ```bash theme={null}
  install --php-version=8.1
  ```

* **`--extension-dir[=EXTENSION-DIR]`**\
  Specifies the directory where the PHP extension should be installed.\
  Example:
  ```bash theme={null}
  install --extension-dir=/usr/local/lib/php/extensions
  ```

**Examples:**

1. Install the Turso libSQL extension with the unstable version and specify a custom `php.ini` file:
   ```bash theme={null}
   install --unstable --php-ini=/etc/php.ini
   ```

2. Install the Thread Safe version for PHP 8.1 and specify the extension directory:
   ```bash theme={null}
   install --thread-safe --php-version=8.1 --extension-dir=/usr/local/lib/php/extensions
   ```

This command is used to install the Turso libSQL extension for PHP, making it easier to integrate libSQL with PHP-based applications. You can customize the installation with options to select specific versions, configurations, or directories based on your environment.

### Interactive Mode

**Command**

```shell theme={null}
turso-php-installer install
```

**Output**

<Frame>
  <img src="https://mintcdn.com/darkterminal/XvKQV4VvldX3mUs-/images/interactive-mode-installation.gif?s=31aae8bc4c443b21b717707458a2cac8" width="1066" height="588" data-path="images/interactive-mode-installation.gif" />
</Frame>

### Non-interactive Mode

**Command**

```shell theme={null}
turso-php-installer install -y --php-version=8.3 --ext-destination=$EXT_DESTINATION
```

**Output**

<Frame>
  <img src="https://mintcdn.com/darkterminal/XvKQV4VvldX3mUs-/images/non-interactive-mode-installation.gif?s=f7e500528c8671dfd35f995d331b8fae" width="1066" height="548" data-path="images/non-interactive-mode-installation.gif" />
</Frame>

<Note>Make sure you have root access when using Non-intractive Mode</Note>

## Update

Update Turso libSQL Extension for PHP.

**Command**

```shell theme={null}
turso-php-installer update
```

**Output**

<Frame>
  <img src="https://mintcdn.com/darkterminal/XvKQV4VvldX3mUs-/images/extension-update.gif?s=625a6a1c71357ca7eeceac4c2836a92b" width="1066" height="548" data-path="images/extension-update.gif" />
</Frame>

## Uninstall

Uninstall Turso libSQL Extension for PHP.

**Command**

```shell theme={null}
turso-php-installer uninstall
```

**Output**

<Frame>
  <img src="https://mintcdn.com/darkterminal/XvKQV4VvldX3mUs-/images/extension-uninstall.gif?s=10d1d3e23b5d931262a3b06b570491cf" width="1066" height="548" data-path="images/extension-uninstall.gif" />
</Frame>

## Version

Display Turso PHP Installer version with Current LibSQL Core and LibSQL PHP Extension.

**Command**

```shell theme={null}
turso-php-installer version
```

**Output**

```shell theme={null}
Turso libSQL Installer (version: 2.0.3)
LibSQL Core Version : 3.45.1-3045001 - LibSQL PHP Extension Version: 1.4.2
```

***

This command will (below 👇) be particularly useful when using the **libSQL Server** on your local computer during the development process. Additional features may be developed in the future to make it easier for developers to use **libSQL Database** and **libSQL Server** without any concerns.

***

## Token Management

The following commands are used to manage database tokens for the libSQL Server during local development. These commands allow developers to create, view, list, and delete tokens as needed.

### `token:create`

Creates a libSQL Server Database token for local development purposes.

**Usage:**

```bash theme={null}
token:create [options] [--] <db-name>
```

**Arguments:**

* **`<db-name>`**\
  The name of the database for which to generate the token.

**Options:**

* **`--expire[=EXPIRE]`**\
  The number of days until the token expires. The default value is 7 days.\
  Example: `--expire=14` will set the token expiration to 14 days.

**Examples:**

1. Create a token for a database named `my_database` with the default 7-day expiration:
   ```bash theme={null}
   token:create my_database
   ```

2. Create a token for a database named `my_database` with a 14-day expiration:
   ```bash theme={null}
   token:create --expire=14 my_database
   ```

### `token:list`

Displays a list of all generated database tokens.

**Usage:**

```bash theme={null}
token:list
```

**Examples:**

1. Display a list of all tokens for all databases:
   ```bash theme={null}
   token:list
   ```

This command provides an overview of all database tokens that have been generated, including their details such as database names, token types, and expiration dates.

### `token:show`

Displays the libSQL Server Database token or related details for local development.

**Usage:**

```bash theme={null}
token:show [options] [--] <db-name>
```

**Arguments:**

* **`<db-name>`**\
  The name of the database for which to display the token or other related details.

**Options:**

* **`--fat`**\
  Display only the full access token.

* **`--roa`**\
  Display only the read-only access token.

* **`--pkp`**\
  Display only the public key in PEM format.

* **`--pkb`**\
  Display only the public key in Base64 format.

**Examples:**

1. Show all tokens and public key details for the `my_database` database:
   ```bash theme={null}
   token:show my_database
   ```

2. Show only the full access token for the `my_database` database:
   ```bash theme={null}
   token:show --fat my_database
   ```

3. Show only the read-only access token for the `my_database` database:
   ```bash theme={null}
   token:show --roa my_database
   ```

4. Show only the public key in PEM format for the `my_database` database:
   ```bash theme={null}
   token:show --pkp my_database
   ```

5. Show only the public key in Base64 format for the `my_database` database:
   ```bash theme={null}
   token:show --pkb my_database
   ```

### `token:delete`

Deletes a specific database token or all tokens for local development.

**Usage:**

```bash theme={null}
token:delete [options] [--] [<db-name>]
```

**Arguments:**

* **`<db-name>`**\
  The name of the database whose token you want to delete. If omitted and `--all` is not specified, the command will fail.

**Options:**

* **`--all`**\
  Deletes all database tokens for all databases. Use with caution, as this action is irreversible.

**Examples:**

1. Delete the token for a specific database named `my_database`:
   ```bash theme={null}
   token:delete my_database
   ```

2. Delete all database tokens:
   ```bash theme={null}
   token:delete --all
   ```

If you intend to delete a specific token, ensure you specify the correct database name to avoid unintentional token deletions.

## Certificate Management

This set of commands provides a comprehensive toolkit for managing server certificates and ensuring server readiness. It includes functionalities to create, delete, and list Certificate Authority (CA) certificates, view raw certificate details, and generate peer certificates. Users can also manage the global certificate store by retrieving or setting its location, with a default setup tied to the installation directory. Additionally, a dedicated command is available to verify server prerequisites, ensuring that necessary components like Python 3, pip, and cryptography libraries are properly installed. These features streamline certificate management and server preparation tasks.

### `server:check`

Checks the server requirements to ensure that necessary components are installed. Specifically, it verifies if:

* **Python 3** is installed.
* **Pip** (Python package manager) is installed.
* **Cryptography library** is installed.

**Usage:**

```bash theme={null}
server:check
```

**Examples:**

1. Run the requirement check:
   ```bash theme={null}
   server:check
   ```

**Output:**\
The command will provide feedback on whether the required components are installed and properly configured. If any components are missing, it will suggest steps to install them.

This command is useful for setting up the server environment and ensuring all prerequisites are met before starting development or deployment.

### `server:ca-cert-create`

Generates a Certificate Authority (CA) certificate for the server.

**Usage:**

```bash theme={null}
server:ca-cert-create [options] [--] [<name>]
```

**Arguments:**

* **`<name>`**\
  The name of the CA certificate to generate. Defaults to `"ca"` if not specified.\
  Example: `my-ca-cert`.

**Options:**

* **`--expiry[=EXPIRY]`**\
  The expiration period of the CA certificate in days. Defaults to 30 days.\
  Example: `--expiry=90` sets the certificate to expire in 90 days.

**Examples:**

1. Generate a CA certificate with the default name `ca` and a 30-day expiration:
   ```bash theme={null}
   server:ca-cert-create
   ```

2. Generate a CA certificate with a custom name `my-ca-cert` and the default 30-day expiration:
   ```bash theme={null}
   server:ca-cert-create my-ca-cert
   ```

3. Generate a CA certificate with a custom name and a 90-day expiration:
   ```bash theme={null}
   server:ca-cert-create --expiry=90 my-ca-cert
   ```

This command is useful for generating CA certificates for securing server communication during development or testing.

### `server:ca-peer-cert-create`

Creates a peer certificate signed by the Certificate Authority (CA).

**Usage:**

```bash theme={null}
server:ca-peer-cert-create [options] [--] [<name>]
```

**Arguments:**

* **`<name>`**\
  The name of the peer certificate to generate. Defaults to `"ca"` if not specified.\
  Example: `peer-cert-1`.

**Options:**

* **`--expiry[=EXPIRY]`**\
  The expiration period of the peer certificate in days. Defaults to 30 days.\
  Example: `--expiry=60` sets the certificate to expire in 60 days.

**Examples:**

1. Create a peer certificate with the default name `ca` and a 30-day expiration:
   ```bash theme={null}
   server:ca-peer-cert-create
   ```

2. Create a peer certificate with a custom name `peer-cert-1` and the default 30-day expiration:
   ```bash theme={null}
   server:ca-peer-cert-create peer-cert-1
   ```

3. Create a peer certificate with a custom name and a 60-day expiration:
   ```bash theme={null}
   server:ca-peer-cert-create --expiry=60 peer-cert-1
   ```

This command is useful for generating peer certificates for secure communication between entities, such as servers or clients, during development or testing.

### `server:ca-cert-list`

Lists all generated Certificate Authority (CA) certificates.

**Usage:**

```bash theme={null}
server:ca-cert-list
```

**Examples:**

1. Display a list of all CA certificates:
   ```bash theme={null}
   server:ca-cert-list
   ```

This command provides an overview of all CA certificates that have been created, including details such as their names, expiration dates, and other metadata. It is useful for managing and reviewing existing certificates during development or testing.

### `server:ca-cert-show`

Displays the raw CA certificate and private key.

**Usage:**

```bash theme={null}
server:ca-cert-show [options]
```

**Options:**

* **`--raw`**\
  Outputs the raw CA certificate and private key directly as text.

**Examples:**

1. Display the raw CA certificate and private key:
   ```bash theme={null}
   server:ca-cert-show --raw
   ```

This command is useful for retrieving the CA certificate and private key in raw format for debugging or integration purposes. Use the `--raw` option to view the certificate and key as plain text.

### `server:ca-cert-delete`

Deletes a specific Certificate Authority (CA) certificate or all CA certificates from the global store location.

**Usage:**

```bash theme={null}
server:ca-cert-delete [options] [--] [<name>]
```

**Arguments:**

* **`<name>`**\
  The name of the CA certificate to delete. Defaults to `"ca"` if not specified.\
  Example: `my-ca-cert`.

**Options:**

* **`--all`**\
  Deletes all CA certificates from the global store location. Use this option with caution as it is irreversible.

**Examples:**

1. Delete a specific CA certificate with the default name `ca`:
   ```bash theme={null}
   server:ca-cert-delete
   ```

2. Delete a specific CA certificate with a custom name `my-ca-cert`:
   ```bash theme={null}
   server:ca-cert-delete my-ca-cert
   ```

3. Delete all CA certificates from the global store location:
   ```bash theme={null}
   server:ca-cert-delete --all
   ```

This command is useful for removing outdated or unnecessary CA certificates to maintain a clean global store. Ensure you specify the correct certificate name or use the `--all` option carefully.

### `server:cert-store-get`

Retrieves the location of the certificate store.

**Usage:**

```bash theme={null}
server:cert-store-get
```

**Examples:**

1. Get the certificate store location:
   ```bash theme={null}
   server:cert-store-get
   ```

This command is useful for identifying the file system path where certificates are stored, allowing for manual inspection, backup, or other management tasks.

### `server:cert-store-set`

Sets or overwrites the global certificate store location to be used by the server. By default, the store location is `{installation_dir}/certs`.

**Usage:**

```bash theme={null}
server:cert-store-set [<path>]
```

**Arguments:**

* **`<path>`**\
  The file system path to set as the new global certificate store.\
  Example: `/custom/path/to/certs`.

**Examples:**

1. Set a custom global certificate store location:
   ```bash theme={null}
   server:cert-store-set /custom/path/to/certs
   ```

2. Reset the certificate store location to the default by not specifying a path:
   ```bash theme={null}
   server:cert-store-set
   ```

This command is useful for customizing the location of the certificate store to suit specific development or deployment needs. Ensure the specified path is accessible and writable by the server.

## SQLD / libSQL Environment Management

This set of commands is designed to efficiently manage SQLD environments and interact with databases. It enables users to create, edit, delete, and list environments, ensuring streamlined organization and easy access for future use. Detailed information about specific environments can also be viewed as needed. Additionally, users can open databases using the Turso CLI and run the SQLD server based on a selected environment, providing a seamless workflow for database and server management.

### `sqld:env-new`

Creates a new `sqld` environment and saves it for future use. If the environment already exists, it can be overwritten using the `--force` option.

**Usage:**

```bash theme={null}
sqld:env-new [options] [--] <name>
```

**Arguments:**

* **`<name>`**\
  The name of the environment to create. This is required.\
  Example: `development`, `staging`, or `production`.

**Options:**

* **`--variables[=VARIABLES]`**\
  Specifies the variables for the environment in either JSON or DSN (Data Source Name) format.\
  Example in JSON format:
  ```bash theme={null}
  --variables='{"SQLD_DB_PATH": "/your/database/path", "SQLD_HTTP_LISTEN_ADDR": "127.0.0.1:8080", "SQLD_AUTH_JWT_KEY_FILE": "/path/to/jwt_key.pem"}'
  ```
  Example in DSN format:
  ```bash theme={null}
  --variables="SQLD_DB_PATH=/your/database/path;SQLD_HTTP_LISTEN_ADDR=127.0.0.1:8080;SQLD_AUTH_JWT_KEY_FILE=/path/to/jwt_key.pem"
  ```

* **`--force`**\
  Forces the creation of the environment by overwriting it if an environment with the same name already exists.

**Examples:**

1. Create a new environment named `development` with variables in JSON format:
   ```bash theme={null}
   sqld:env-new development --variables='{"SQLD_DB_PATH": "/your/database/path", "SQLD_HTTP_LISTEN_ADDR": "127.0.0.1:8080", "SQLD_AUTH_JWT_KEY_FILE": "/path/to/jwt_key.pem"}'
   ```

2. Create a new environment named `production` with variables in DSN format:
   ```bash theme={null}
   sqld:env-new production --variables="SQLD_DB_PATH=/your/database/path;SQLD_HTTP_LISTEN_ADDR=127.0.0.1:8080;SQLD_AUTH_JWT_KEY_FILE=/path/to/jwt_key.pem"
   ```

3. Overwrite an existing environment named `staging`:
   ```bash theme={null}
   sqld:env-new staging --force
   ```

This command is useful for setting up and managing different environments (e.g., development, staging, production) with their respective configurations for `sqld`.

### `sqld:env-list`

Lists all created `sqld` environments.

**Usage:**

```bash theme={null}
sqld:env-list
```

**Examples:**

1. List all available environments:
   ```bash theme={null}
   sqld:env-list
   ```

This command is useful for getting an overview of all environments that have been created, allowing you to quickly see which environments are available for use or management.

### `sqld:env-show`

Displays detailed information about a specific `sqld` environment based on its name or ID.

**Usage:**

```bash theme={null}
sqld:env-show <name-or-id>
```

**Arguments:**

* **`<name-or-id>`**\
  The name or ID of the environment whose details you want to view.\
  Example: `development`, `staging`, or an environment ID like `677e5e0155167`.

**Examples:**

1. Show details of an environment named `development`:
   ```bash theme={null}
   sqld:env-show development
   ```

2. Show details of an environment by its ID:
   ```bash theme={null}
   sqld:env-show 677e5e0155167
   ```

The output includes information such as environment variables, configurations, and other relevant details, making this command useful for reviewing or debugging specific environments.

### `sqld:env-edit`

Edits an existing `sqld` environment by its ID or name.

**Usage:**

```bash theme={null}
sqld:env-edit <env-id-or-name>
```

**Arguments:**

* **`<env-id-or-name>`**\
  The ID or name of the environment you want to edit.\
  Example: `development`, `staging`, or `677e5e0155167`.

**Examples:**

1. Edit an environment named `development`:
   ```bash theme={null}
   sqld:env-edit development
   ```

2. Edit an environment by its ID, for example, `677e5e0155167`:
   ```bash theme={null}
   sqld:env-edit 677e5e0155167
   ```

This command allows you to modify an existing environment's settings and configurations. It's useful for updating environment details such as database connections, credentials, or any other environment-specific variables.

### `sqld:env-delete`

Deletes an `sqld` environment by its name or ID.

**Usage:**

```bash theme={null}
sqld:env-delete <name-or-id>
```

**Arguments:**

* **`<name-or-id>`**\
  The name or ID of the environment you want to delete.\
  Example: `development`, `staging`, or `677e5e0155167`.

**Examples:**

1. Delete an environment named `development`:
   ```bash theme={null}
   sqld:env-delete development
   ```

2. Delete an environment by its ID, for example, `677e5e0155167`:
   ```bash theme={null}
   sqld:env-delete 677e5e0155167
   ```

This command is useful for removing environments that are no longer needed. Once deleted, the environment and its associated configurations will be permanently removed.

### `sqld:server-run`

Runs the `sqld` server based on the specified environment ID or name, and connects it to the specified database. This command also will return a URL to open SQLD Studio in browser with current database credential / running database.

**Usage:**

```bash theme={null}
sqld:server-run [options] [--] <env-id-or-name> <db-name>
```

**Arguments:**

* **`<env-id-or-name>`**\
  The ID or name of the environment in which to run the `sqld` server.\
  Example: `development`, `staging`, or `677e5e0155167`.

* **`<db-name>`**\
  The name of the database to connect the server to.\
  Example: `my_database`.

**Options:**

* **`-d, --daemon`**\
  Runs the `sqld` server in daemon mode, allowing it to run in the background.

**Examples:**

1. Run the `sqld` server for the `development` environment and connect to the `my_database` database:
   ```bash theme={null}
   sqld:server-run development my_database
   ```

2. Run the `sqld` server for the `staging` environment, connect to the `prod_db` database, and run it in daemon mode:
   ```bash theme={null}
   sqld:server-run -d staging prod_db
   ```

This command is used to start the `sqld` server in a specified environment and connect it to a database. The `--daemon` option is useful for running the server in the background without blocking the terminal.

### `sqld:open-db`

Opens a database using the Turso CLI for the specified environment and database in Turso Database Shell.

**Usage:**

```bash theme={null}
sqld:open-db <env-id-or-name> <db-name>
```

**Arguments:**

* **`<env-id-or-name>`**\
  The ID or name of the environment where the database is located.\
  Example: `development`, `staging`, or `677e5e0155167`.

* **`<db-name>`**\
  The name of the database to open.\
  Example: `my_database`.

**Examples:**

1. Open the `my_database` from the `development` environment:
   ```bash theme={null}
   sqld:open-db development my_database
   ```

2. Open the `prod_db` from the `staging` environment:
   ```bash theme={null}
   sqld:open-db staging prod_db
   ```

This command allows you to open and interact with a specific database in a given environment using the Turso CLI, which is useful for managing and querying your databases directly.