Can I use Hugging Face as a CLI?

Yes. KosmoKrator exposes a Hugging Face CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Hugging Face through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Hugging Face tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Hugging Face credentials stored?

Hugging Face credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Hugging Face MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

data

Hugging Face Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Hugging Face KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.hugging_face.*. Use lua_read_doc("integrations.hugging-face") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Hugging Face workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.hugging_face.list_models({search = "example_search", author = "example_author", task = "example_task", tags = "example_tags", sort = "example_sort", direction = "example_direction", limit = 1, offset = 1}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("hugging-face"))' --json
kosmo integrations:lua --eval 'print(docs.read("hugging-face.list_models"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local hugging_face = app.integrations.hugging_face
local result = hugging_face.list_models({search = "example_search", author = "example_author", task = "example_task", tags = "example_tags", sort = "example_sort", direction = "example_direction", limit = 1, offset = 1})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.hugging_face, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.hugging_face.default.* or app.integrations.hugging_face.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Hugging Face, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Hugging Face Lua API Reference

Namespace: app.integrations["hugging-face"]

This integration wraps the Hugging Face Hub API and the serverless Inference API. Repository IDs keep their owner slash, for example meta-llama/Llama-3.3-70B-Instruct.

Discovery

Use list_models, list_datasets, and list_spaces for Hub search. Common filters include search, author, tags, sort, direction, limit, and offset. list_models also accepts task, which maps to the Hub pipeline_tag filter.

local models = app.integrations["hugging-face"].list_models({
  task = "text-generation",
  sort = "downloads",
  limit = 10
})

Use get_model, get_dataset, and get_space when you already have a repo ID and need metadata, tags, card data, likes, downloads, or file siblings.

local model = app.integrations["hugging-face"].get_model({
  model_id = "meta-llama/Llama-3.3-70B-Instruct"
})

local dataset = app.integrations["hugging-face"].get_dataset({
  dataset_id = "mozilla-foundation/common_voice_17_0"
})

Repository Utilities

The repo tools accept repo_type as models, datasets, or spaces. Singular values like model are also accepted.

local refs = app.integrations["hugging-face"].list_refs({
  repo_type = "models",
  repo_id = "bert-base-uncased"
})

local commits = app.integrations["hugging-face"].list_commits({
  repo_type = "datasets",
  repo_id = "mozilla-foundation/common_voice_17_0",
  revision = "main"
})

local files = app.integrations["hugging-face"].list_tree({
  repo_type = "spaces",
  repo_id = "organization/demo-space",
  revision = "main",
  path = "src"
})

Use get_scan_status to inspect Hub security scan status for a model, dataset, or Space repository.

Metadata Helpers

list_model_tags and list_dataset_tags return Hub tag dictionaries grouped by type. Use these before building filter-heavy searches. list_space_hardware returns the hardware options exposed by the Hub.

Create Repositories

create_repo calls the official Hub repository creation endpoint. Use type values model, dataset, or space.

local repo = app.integrations["hugging-face"].create_repo({
  name = "demo-space",
  type = "space",
  private = true,
  sdk = "gradio"
})

Inference

inference sends requests to the configured serverless model router. The response shape depends on the model task.

local result = app.integrations["hugging-face"].inference({
  model_id = "facebook/bart-large-cnn",
  inputs = "Long text to summarize...",
  parameters = {
    max_new_tokens = 128
  }
})

Generic Hub API Calls

Use api_get, api_post, api_put, and api_delete for official relative Hub API paths that are not wrapped yet. Absolute URLs are rejected; pass paths such as /models-tags-by-type, not full URLs.

local tags = app.integrations["hugging-face"].api_get({
  path = "/models-tags-by-type"
})

Account

get_current_user calls the current /whoami-v2 endpoint and returns the authenticated account metadata.

Raw agent markdown

# Hugging Face Lua API Reference

Namespace: `app.integrations["hugging-face"]`

This integration wraps the Hugging Face Hub API and the serverless Inference API. Repository IDs keep their owner slash, for example `meta-llama/Llama-3.3-70B-Instruct`.

## Discovery

Use `list_models`, `list_datasets`, and `list_spaces` for Hub search. Common filters include `search`, `author`, `tags`, `sort`, `direction`, `limit`, and `offset`. `list_models` also accepts `task`, which maps to the Hub `pipeline_tag` filter.

```lua
local models = app.integrations["hugging-face"].list_models({
  task = "text-generation",
  sort = "downloads",
  limit = 10
})
```

Use `get_model`, `get_dataset`, and `get_space` when you already have a repo ID and need metadata, tags, card data, likes, downloads, or file siblings.

```lua
local model = app.integrations["hugging-face"].get_model({
  model_id = "meta-llama/Llama-3.3-70B-Instruct"
})

local dataset = app.integrations["hugging-face"].get_dataset({
  dataset_id = "mozilla-foundation/common_voice_17_0"
})
```

## Repository Utilities

The repo tools accept `repo_type` as `models`, `datasets`, or `spaces`. Singular values like `model` are also accepted.

```lua
local refs = app.integrations["hugging-face"].list_refs({
  repo_type = "models",
  repo_id = "bert-base-uncased"
})

local commits = app.integrations["hugging-face"].list_commits({
  repo_type = "datasets",
  repo_id = "mozilla-foundation/common_voice_17_0",
  revision = "main"
})

local files = app.integrations["hugging-face"].list_tree({
  repo_type = "spaces",
  repo_id = "organization/demo-space",
  revision = "main",
  path = "src"
})
```

Use `get_scan_status` to inspect Hub security scan status for a model, dataset, or Space repository.

## Metadata Helpers

`list_model_tags` and `list_dataset_tags` return Hub tag dictionaries grouped by type. Use these before building filter-heavy searches. `list_space_hardware` returns the hardware options exposed by the Hub.

## Create Repositories

`create_repo` calls the official Hub repository creation endpoint. Use `type` values `model`, `dataset`, or `space`.

```lua
local repo = app.integrations["hugging-face"].create_repo({
  name = "demo-space",
  type = "space",
  private = true,
  sdk = "gradio"
})
```

## Inference

`inference` sends requests to the configured serverless model router. The response shape depends on the model task.

```lua
local result = app.integrations["hugging-face"].inference({
  model_id = "facebook/bart-large-cnn",
  inputs = "Long text to summarize...",
  parameters = {
    max_new_tokens = 128
  }
})
```

## Generic Hub API Calls

Use `api_get`, `api_post`, `api_put`, and `api_delete` for official relative Hub API paths that are not wrapped yet. Absolute URLs are rejected; pass paths such as `/models-tags-by-type`, not full URLs.

```lua
local tags = app.integrations["hugging-face"].api_get({
  path = "/models-tags-by-type"
})
```

## Account

`get_current_user` calls the current `/whoami-v2` endpoint and returns the authenticated account metadata.

Metadata-derived Lua example

local result = app.integrations.hugging_face.list_models({search = "example_search", author = "example_author", task = "example_task", tags = "example_tags", sort = "example_sort", direction = "example_direction", limit = 1, offset = 1})
print(result)

Functions

list_models Read

Search and list AI models on the Hugging Face Hub. Filter by text search, author, task (e.g. "text-generation", "image-classification"), tags, and sort by downloads, likes, or recent activity.

Lua path: app.integrations.hugging_face.list_models
Full name: hugging-face.huggingface_list_models

Parameter	Type	Required	Description
`search`	string	no	Search query to filter models by name or description.
`author`	string	no	Filter by organization or user (e.g. "meta-llama", "openai").
`task`	string	no	Filter by pipeline task (e.g. "text-generation", "text-classification", "image-classification", "automatic-speech-recognition").
`tags`	array	no	Filter by tags (e.g. ["pytorch", "safetensors"]).
`sort`	string	no	Sort order: "downloads", "likes", "lastModified", "created". Defaults to "downloads".
`direction`	string	no	Sort direction: "asc" or "desc". Defaults to "desc".
`limit`	integer	no	Number of results per page (default: 20, max: 500).
`offset`	integer	no	Offset for pagination.

get_model Read

Get detailed information about a specific Hugging Face model, including its card, tags, pipeline tag, library, downloads, likes, and file listing.

Lua path: app.integrations.hugging_face.get_model
Full name: hugging-face.huggingface_get_model

Parameter	Type	Required	Description
`model_id`	string	yes	The model ID (e.g. "meta-llama/Llama-3.3-70B-Instruct", "bert-base-uncased").

list_datasets Read

Search and list datasets on the Hugging Face Hub. Filter by text search, author, tags, and sort by downloads, likes, or recent activity.

Lua path: app.integrations.hugging_face.list_datasets
Full name: hugging-face.huggingface_list_datasets

Parameter	Type	Required	Description
`search`	string	no	Search query to filter datasets by name or description.
`author`	string	no	Filter by organization or user (e.g. "HuggingFaceFW", "mozilla-foundation").
`tags`	array	no	Filter by tags (e.g. ["text-classification", "english"]).
`sort`	string	no	Sort order: "downloads", "likes", "lastModified", "created". Defaults to "downloads".
`direction`	string	no	Sort direction: "asc" or "desc". Defaults to "desc".
`limit`	integer	no	Number of results per page (default: 20, max: 500).
`offset`	integer	no	Offset for pagination.

get_dataset Read

Get detailed information about a Hugging Face dataset, including card data, tags, downloads, likes, and files.

Lua path: app.integrations.hugging_face.get_dataset
Full name: hugging-face.huggingface_get_dataset

Parameter	Type	Required	Description
`dataset_id`	string	yes	Dataset ID, for example "mozilla-foundation/common_voice_17_0".

run_inference Write

Run inference on a Hugging Face model via the serverless Inference API. Supports text generation, summarization, translation, classification, image analysis, and more. The payload structure depends on the model's task; refer to the Hugging Face Inference API docs for model-specific formats.

Lua path: app.integrations.hugging_face.run_inference
Full name: hugging-face.huggingface_inference

Parameter	Type	Required	Description
`model_id`	string	yes	The model ID to run inference on (e.g. "meta-llama/Llama-3.3-70B-Instruct", "facebook/bart-large-cnn").
`inputs`	string	no	The input text or data for the model. For text tasks, this is the prompt or text to process.
`parameters`	object	no	Model-specific parameters (e.g. {"max_new_tokens": 256, "temperature": 0.7, "top_p": 0.95} for text generation).
`data`	string	no	Base64-encoded data for image/audio tasks. Use this instead of "inputs" for non-text models.

list_spaces Read

Search and list Spaces on the Hugging Face Hub. Filter by text search, author, tags, SDK, and sort by downloads, likes, or recent activity.

Lua path: app.integrations.hugging_face.list_spaces
Full name: hugging-face.huggingface_list_spaces

Parameter	Type	Required	Description
`search`	string	no	Search query to filter Spaces by name or description.
`author`	string	no	Filter by organization or user (e.g. "gradio", "stabilityai").
`tags`	array	no	Filter by tags (e.g. ["gradio", "text-generation"]).
`sort`	string	no	Sort order: "downloads", "likes", "lastModified", "created". Defaults to "downloads".
`direction`	string	no	Sort direction: "asc" or "desc". Defaults to "desc".
`limit`	integer	no	Number of results per page (default: 20, max: 500).
`offset`	integer	no	Offset for pagination.

get_space Read

Get detailed information about a Hugging Face Space, including SDK, runtime, tags, likes, and files.

Lua path: app.integrations.hugging_face.get_space
Full name: hugging-face.huggingface_get_space

Parameter	Type	Required	Description
`space_id`	string	yes	Space ID, for example "organization/space-name".

get_current_user Read

Get the authenticated Hugging Face user's profile information, including name, username, type (user/org), and avatar.

Lua path: app.integrations.hugging_face.get_current_user
Full name: hugging-face.huggingface_get_current_user

Parameter	Type	Required	Description
No parameters.

list_commits Read

List commits for a Hugging Face model, dataset, or Space repository at a revision.

Lua path: app.integrations.hugging_face.list_commits
Full name: hugging-face.huggingface_list_commits

Parameter	Type	Required	Description
`repo_type`	string	yes	Repository type. Singular values are also accepted.
`repo_id`	string	yes	Repository ID, for example "meta-llama/Llama-3.3-70B-Instruct".
`revision`	string	no	Revision, branch, or tag. Defaults to "main".

list_refs Read

List branches, tags, and refs for a Hugging Face model, dataset, or Space repository.

Lua path: app.integrations.hugging_face.list_refs
Full name: hugging-face.huggingface_list_refs

Parameter	Type	Required	Description
`repo_type`	string	yes	Repository type. Singular values are also accepted.
`repo_id`	string	yes	Repository ID.

list_tree Read

List repository tree contents for a model, dataset, or Space at a revision and optional nested path.

Lua path: app.integrations.hugging_face.list_tree
Full name: hugging-face.huggingface_list_tree

Parameter	Type	Required	Description
`repo_type`	string	yes	Repository type. Singular values are also accepted.
`repo_id`	string	yes	Repository ID.
`revision`	string	no	Revision, branch, or tag. Defaults to "main".
`path`	string	no	Nested folder path inside the repository.
`params`	object	no	Optional Hub API query parameters, such as recursive or expand when supported.

get_scan_status Read

Get the Hugging Face Hub security scan status for a model, dataset, or Space repository.

Lua path: app.integrations.hugging_face.get_scan_status
Full name: hugging-face.huggingface_get_scan_status

Parameter	Type	Required	Description
`repo_type`	string	yes	Repository type. Singular values are also accepted.
`repo_id`	string	yes	Repository ID.

list_model_tags Read

List Hugging Face model tags grouped by type, such as task, library, language, and license.

Lua path: app.integrations.hugging_face.list_model_tags
Full name: hugging-face.huggingface_list_model_tags

Parameter	Type	Required	Description
No parameters.

list_dataset_tags Read

List Hugging Face dataset tags grouped by type, such as task category, language, modality, and license.

Lua path: app.integrations.hugging_face.list_dataset_tags
Full name: hugging-face.huggingface_list_dataset_tags

Parameter	Type	Required	Description
No parameters.

list_space_hardware Read

List Hugging Face Space hardware options for creating or upgrading Spaces.

Lua path: app.integrations.hugging_face.list_space_hardware
Full name: hugging-face.huggingface_list_space_hardware

Parameter	Type	Required	Description
No parameters.

create_repository Write

Create a Hugging Face model, dataset, or Space repository. Use type values "model", "dataset", or "space".

Lua path: app.integrations.hugging_face.create_repository
Full name: hugging-face.huggingface_create_repo

Parameter	Type	Required	Description
`name`	string	yes	Repository name without owner prefix.
`type`	string	yes	Repository type.
`organization`	string	no	Optional organization owner. Omit for the authenticated user.
`private`	boolean	no	Whether the repository should be private.
`sdk`	string	no	Space SDK when creating a Space, for example "gradio", "streamlit", "docker", or "static".
`license`	string	no	Optional license identifier.
`extra`	object	no	Additional official repository creation fields to pass through.

api_get Read

Call a relative Hugging Face Hub API GET path, such as "/models-tags-by-type". Absolute URLs are rejected.

Lua path: app.integrations.hugging_face.api_get
Full name: hugging-face.huggingface_api_get

Parameter	Type	Required	Description
`path`	string	yes	Relative Hub API path, with or without leading slash.
`params`	object	no	Query parameters.

api_post Write

Call a relative Hugging Face Hub API POST path with a JSON body. Absolute URLs are rejected.

Lua path: app.integrations.hugging_face.api_post
Full name: hugging-face.huggingface_api_post

Parameter	Type	Required	Description
`path`	string	yes	Relative Hub API path, with or without leading slash.
`payload`	object	no	JSON request body.

api_put Write

Call a relative Hugging Face Hub API PUT path with a JSON body. Absolute URLs are rejected.

Lua path: app.integrations.hugging_face.api_put
Full name: hugging-face.huggingface_api_put

Parameter	Type	Required	Description
`path`	string	yes	Relative Hub API path, with or without leading slash.
`payload`	object	no	JSON request body.

api_delete Write

Call a relative Hugging Face Hub API DELETE path. Absolute URLs are rejected.

Lua path: app.integrations.hugging_face.api_delete
Full name: hugging-face.huggingface_api_delete

Parameter	Type	Required	Description
`path`	string	yes	Relative Hub API path, with or without leading slash.
`payload`	object	no	Optional JSON request body.