LuaRocks Documentation

https://luarocks.org/docs
Admin
Guides and references for using LuaRocks, the package manager for the Lua programming language,...
Tokens:3,581
Snippets:44
Trust Score:9.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install from User Manifest

Source: https://luarocks.org/docs

Installs a package from a user-specific manifest. This is useful for installing modules published by a particular user.

```bash
luarocks install --server=https://luarocks.org/manifests/luarocks lpeg

```

--------------------------------

### Install from GitHub Mirror (Development)

Source: https://luarocks.org/docs

Installs a development version of a package using a GitHub repository mirror. This provides a fallback for accessing development versions.

```bash
luarocks install --server=https://raw.githubusercontent.com/rocks-moonscript-org/moonrocks-dev-mirror/master lpeg

```

--------------------------------

### Install from Default Manifest

Source: https://luarocks.org/docs

Installs a package using the default LuaRocks manifest. This is the most common way to install stable modules.

```bash
luarocks install lpeg

```

--------------------------------

### Install from Custom Manifest

Source: https://luarocks.org/docs

Installs a package from a custom manifest. This allows you to use your own curated list of modules.

```bash
luarocks install --server=https://luarocks.org/m/mymanifest mymodule

```

--------------------------------

### Install Development Version

Source: https://luarocks.org/docs

Installs a development version of a package by specifying the development server path. Use this when you need the latest, potentially unstable, features.

```bash
luarocks install --server=https://luarocks.org/dev lpeg

```

--------------------------------

### Install from GitHub Mirror (Stable)

Source: https://luarocks.org/docs

Installs a package using a GitHub repository mirror as a LuaRocks server. This can serve as a fallback if the main LuaRocks.org server is unavailable.

```bash
luarocks install --server=https://raw.githubusercontent.com/rocks-moonscript-org/moonrocks-mirror/master lpeg

```

--------------------------------

### Specify Manifest Root Path for Installation

Source: https://luarocks.org/docs

Use the `--server` option to specify which manifest root path to install from. This is useful for installing packages from development servers or user-specific manifests.

```bash
luarocks install --server=<root-path> <module-name>

```

--------------------------------

### Upload Rock API Response Example

Source: https://luarocks.org/docs/api

This is an example of a successful JSON response when uploading a compiled rock file via the API.

```json
{
  "rock": {
    "id": 789,
    "arch": "linux-x86_64",
    "revision": 1
  },
  "module_url": "https://luarocks.org/modules/username/mymodule"
}

```

--------------------------------

### Get Tool Version

Source: https://luarocks.org/docs/api

Returns the current tool version configured on the server. No authentication is required for this endpoint.

```APIDOC
## Get Tool Version

### Description
Returns the current tool version configured on the server.

### Method
GET

### Endpoint
/api/tool_version

### Authentication
None required

### Response
#### Success Response (200)
- **version** (string) - The current tool version.
```

--------------------------------

### Get API Key Status

Source: https://luarocks.org/docs/api

Check the status of your API key and retrieve your user ID. Authentication is required.

```APIDOC
## Get API Key Status

### Description
Check the status of your API key and get your user ID.

### Method
GET

### Endpoint
/api/1/:key/status

### Authentication
Required

### Response
#### Success Response (200)
- **user_id** (integer) - The user ID associated with the API key.
- **created_at** (string) - The timestamp when the API key was created.
```

--------------------------------

### Get Tool Version

Source: https://luarocks.org/docs/api

Retrieve the current tool version configured on the LuaRocks server. No authentication is required for this endpoint.

```http
GET /api/tool_version


```

```json
{
  "version": "3.0.0"
}


```

--------------------------------

### Get API Key Status

Source: https://luarocks.org/docs/api

Check the status of your API key and retrieve your user ID. Authentication is required.

```http
GET /api/1/:key/status


```

```json
{
  "user_id": 123,
  "created_at": "2024-01-15 10:30:00"
}


```

--------------------------------

### Upload Rock using LuaRocks CLI

Source: https://luarocks.org/docs/api

The LuaRocks CLI provides a convenient way to upload a rockspec, which by default also builds and uploads the compiled rock. Use the --api-key flag to authenticate.

```bash
luarocks upload mymodule-1.0-1.rockspec --api-key=YOUR_API_KEY

```

--------------------------------

### Upload with URL Path Authentication (Legacy)

Source: https://luarocks.org/docs/api

Include the API key directly in the URL path for authentication. This method is considered legacy.

```http
POST /api/1/YOUR_API_KEY/upload


```

--------------------------------

### Check Rockspec Existence

Source: https://luarocks.org/docs/api

Verify if a specific package and version already exists in your account. Authentication is required. Parameters for package and version are case-insensitive.

```http
GET /api/1/:key/check_rockspec?package=:package&version=:version


```

```json
{
  "module": { ... },
  "version": { ... }
}


```

--------------------------------

### Manifest File Structure

Source: https://luarocks.org/docs

Manifest files are Lua tables that define the structure of the module repository, including module names, versions, and available architectures. The `repository` table maps module names to versions and their corresponding architectures.

```lua
{
  repository = {
    ["module_name"] = {
      ["version"] = {
        { arch = "rockspec" },
        { arch = "linux-x86_64" },
        -- additional architectures...
      }
    }
  },
  commands = {},
  modules = {}
}

```

--------------------------------

### Check Rockspec

Source: https://luarocks.org/docs/api

Check if a specific package version already exists in your account. Authentication is required.

```APIDOC
## Check Rockspec

### Description
Check if a specific package version already exists in your account.

### Method
GET

### Endpoint
/api/1/:key/check_rockspec

### Authentication
Required

### Parameters
#### Query Parameters
- **package** (string) - Required - The package name (case-insensitive)
- **version** (string) - Required - The version string (case-insensitive)

### Response
#### Success Response (200)
- **module** (object) - Details about the module, or null if not found.
- **version** (object) - Details about the specific version, or null if not found.
```

--------------------------------

### Upload with Authorization Header

Source: https://luarocks.org/docs/api

Use the Authorization header for API key authentication when uploading. This is the recommended method.

```http
POST /api/1/bearer/upload
Authorization: Bearer YOUR_API_KEY


```

--------------------------------

### Upload Rockspec

Source: https://luarocks.org/docs/api

Upload a new rockspec file. This will create a new module if it doesn’t exist, or add a new version to an existing module. Authentication is required.

```APIDOC
## Upload Rockspec

### Description
Upload a new rockspec file. This will create a new module if it doesn’t exist, or add a new version to an existing module.

### Method
POST

### Endpoint
/api/1/:key/upload

### Authentication
Required

### Parameters
#### Path Parameters
- **key** (string) - Required - Your API key.

#### Request Body
- **rockspec_file** (file) - Required - The `.rockspec` file to upload.
- **tfa_token** (string) - If TFA required - A token from Verify TFA. May also be sent as the `X-TFA-Token` header.

### Response
#### Success Response (200)
- **module** (object) - Information about the uploaded module.
- **version** (object) - Information about the uploaded version.
- **module_url** (string) - The URL to the uploaded module on LuaRocks.org.
- **manifests** (array) - A list of manifests associated with the upload.
- **is_new** (boolean) - Indicates if a new module was created (`true`) or a version was added to an existing module (`false`).
```

--------------------------------

### Upload Rock

Source: https://luarocks.org/docs/api

Upload a compiled rock file for an existing version. This endpoint requires authentication and specific content types.

```APIDOC
## POST /api/1/:key/upload_rock/:version_id

### Description
Upload a compiled rock file for an existing version.

### Method
POST

### Endpoint
/api/1/:key/upload_rock/:version_id

### Parameters
#### Path Parameters
- **key** (string) - Required - The API key for authentication.
- **version_id** (integer) - Required - The version ID of the rock.

#### Form Data Parameters
- **rock_file** (file) - Required - The `.rock` file to upload.
- **tfa_token** (string) - Optional - A token from Verify TFA. May also be sent as the `X-TFA-Token` header.

### Request Example
```
POST /api/1/YOUR_API_KEY/upload_rock/123
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="rock_file"; filename="mymodule-1.0-1.rock"
Content-Type: application/octet-stream

[binary content of the rock file]
--boundary
Content-Disposition: form-data; name="tfa_token"

YOUR_TFA_TOKEN
--boundary--
```

### Response
#### Success Response (200)
- **rock** (object) - Information about the uploaded rock.
  - **id** (integer) - The ID of the uploaded rock.
  - **arch** (string) - The architecture of the rock.
  - **revision** (integer) - The revision number of the rock.
- **module_url** (string) - The URL to the uploaded module.

#### Response Example
```json
{
  "rock": {
    "id": 789,
    "arch": "linux-x86_64",
    "revision": 1
  },
  "module_url": "https://luarocks.org/modules/username/mymodule"
}
```

### Errors
- `404` - Invalid version ID
```

--------------------------------

### Upload Only Rockspec using LuaRocks CLI

Source: https://luarocks.org/docs/api

To upload only the rockspec file without building and uploading the compiled rock, use the --skip-pack flag in addition to the --api-key flag.

```bash
luarocks upload mymodule-1.0-1.rockspec --api-key=YOUR_API_KEY --skip-pack

```

--------------------------------

### Upload Compiled Rock API Endpoint

Source: https://luarocks.org/docs/api

Use this POST endpoint to upload a compiled rock file for an existing version. Authentication is required, and the content type must be multipart/form-data. The version_id is part of the URL, and the rock_file is a required form parameter. An optional tfa_token can be provided for two-factor authentication.

```http
POST /api/1/:key/upload_rock/:version_id

```

--------------------------------

### Upload Rockspec File

Source: https://luarocks.org/docs/api

Upload a new rockspec file to create a module or add a new version. Authentication is required. The TFA token can be sent as form data or a header.

```http
POST /api/1/:key/upload


```

```json
{
  "module": {
    "id": 123,
    "name": "mymodule",
    "current_version_id": 456
  },
  "version": {
    "id": 456,
    "version_name": "1.0-1",
    "module_id": 123
  },
  "module_url": "https://luarocks.org/modules/username/mymodule",
  "manifests": [
    {
      "id": 1,
      "name": "root"
    }
  ],
  "is_new": true
}


```

--------------------------------

### General Error Response Format

Source: https://luarocks.org/docs/api

All API endpoints return JSON. On error, the response will contain an 'errors' array with a descriptive message.

```json
{
  "errors": ["Error message here"]
}


```

--------------------------------

### Verify Two-Factor Authentication

Source: https://luarocks.org/docs/api

Exchange a TOTP code for a short-lived TFA token. This token is required for uploads if TFA is enabled. Authentication is required.

```http
POST /api/1/:key/verify_tfa


```

```json
{
  "success": true,
  "tfa_token": "...",
  "expires": 1700000000
}


```

--------------------------------

### Verify TFA

Source: https://luarocks.org/docs/api

Exchange a TOTP code for a short-lived token that authorizes upload requests when two-factor authentication is required. Authentication is required.

```APIDOC
## Verify TFA

### Description
Exchange a TOTP code for a short-lived token that authorizes upload requests when two-factor authentication is required.

### Method
POST

### Endpoint
/api/1/:key/verify_tfa

### Authentication
Required

### Parameters
#### Path Parameters
- **key** (string) - Required - Your API key.

#### Request Body
- **code** (string) - Required - A TOTP code from the account’s authenticator app.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the TFA verification was successful.
- **tfa_token** (string) - The short-lived token for TFA authorization.
- **expires** (integer) - The expiration timestamp of the TFA token.
```

--------------------------------

### Two-Factor Authentication Required Response

Source: https://luarocks.org/docs/api

This JSON response indicates that two-factor authentication is required for the request.

```json
{
  "errors": ["Two-factor authentication required"],
  "two_factor_required": true
}


```
Tokens:
Raw