Can I use Bitly as a CLI?

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

Can I expose Bitly through MCP?

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

Where are Bitly credentials stored?

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

Can I deny write access for Bitly MCP tools?

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

productivity

Bitly Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.bitly.*. Use lua_read_doc("integrations.bitly") 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 Bitly workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.bitly.shorten_link({long_url = "example_long_url", domain = "example_domain", group_guid = "example_group_guid"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("bitly"))' --json
kosmo integrations:lua --eval 'print(docs.read("bitly.shorten_link"))' --json

Workflow file

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

workflow.lua

local bitly = app.integrations.bitly
local result = bitly.shorten_link({long_url = "example_long_url", domain = "example_domain", group_guid = "example_group_guid"})

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.bitly, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.bitly.default.* or app.integrations.bitly.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Bitly, 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.

Bitly Lua Reference

Namespace: bitly

Bitly tools target API v4 and use bearer access tokens.

Links

local short = app.integrations.bitly.shorten_link({
  long_url = "https://example.test/campaign",
})

local created = app.integrations.bitly.create_bitlink({
  long_url = "https://example.test/landing-page",
  title = "Campaign",
  tags = {"campaign"},
})

local link = app.integrations.bitly.get_link({ bitlink = "bit.ly/abc123" })
local expanded = app.integrations.bitly.expand_bitlink({ bitlink = "bit.ly/abc123" })

local updated = app.integrations.bitly.update_link({
  bitlink = "bit.ly/abc123",
  title = "Updated campaign",
  archived = false,
})

Custom Bitlinks require a custom domain:

local custom = app.integrations.bitly.add_custom_bitlink({
  custom_bitlink = "links.example.test/campaign",
  bitlink_id = "links.example.test/abc123",
})

Analytics

local clicks = app.integrations.bitly.get_clicks({
  bitlink = "bit.ly/abc123",
  unit = "day",
  units = 30,
})

local summary = app.integrations.bitly.get_click_summary({
  bitlink = "bit.ly/abc123",
  params = { unit = "day", units = 30 },
})

local countries = app.integrations.bitly.get_click_countries({
  bitlink = "bit.ly/abc123",
  params = { unit = "day", units = 30, size = 10 },
})

Groups, QR Codes, And Webhooks

local groups = app.integrations.bitly.list_groups({})
local group_links = app.integrations.bitly.list_group_bitlinks({
  group_guid = "group_guid",
  params = { size = 25 },
})

local qr = app.integrations.bitly.create_qr_code({
  body = {
    title = "Campaign QR",
    destination = { bitlink_id = "bit.ly/abc123" },
  },
})

local webhooks = app.integrations.bitly.list_organization_webhooks({
  organization_guid = "org_guid",
})

Generic API

local result = app.integrations.bitly.api_get({
  path = "/groups",
})

Generic write tools:

api_post({ path, body })
api_patch({ path, body })
api_delete({ path, body })

Raw agent markdown

# Bitly Lua Reference

Namespace: `bitly`

Bitly tools target API v4 and use bearer access tokens.

## Links

```lua
local short = app.integrations.bitly.shorten_link({
  long_url = "https://example.test/campaign",
})

local created = app.integrations.bitly.create_bitlink({
  long_url = "https://example.test/landing-page",
  title = "Campaign",
  tags = {"campaign"},
})

local link = app.integrations.bitly.get_link({ bitlink = "bit.ly/abc123" })
local expanded = app.integrations.bitly.expand_bitlink({ bitlink = "bit.ly/abc123" })

local updated = app.integrations.bitly.update_link({
  bitlink = "bit.ly/abc123",
  title = "Updated campaign",
  archived = false,
})
```

Custom Bitlinks require a custom domain:

```lua
local custom = app.integrations.bitly.add_custom_bitlink({
  custom_bitlink = "links.example.test/campaign",
  bitlink_id = "links.example.test/abc123",
})
```

## Analytics

```lua
local clicks = app.integrations.bitly.get_clicks({
  bitlink = "bit.ly/abc123",
  unit = "day",
  units = 30,
})

local summary = app.integrations.bitly.get_click_summary({
  bitlink = "bit.ly/abc123",
  params = { unit = "day", units = 30 },
})

local countries = app.integrations.bitly.get_click_countries({
  bitlink = "bit.ly/abc123",
  params = { unit = "day", units = 30, size = 10 },
})
```

## Groups, QR Codes, And Webhooks

```lua
local groups = app.integrations.bitly.list_groups({})
local group_links = app.integrations.bitly.list_group_bitlinks({
  group_guid = "group_guid",
  params = { size = 25 },
})

local qr = app.integrations.bitly.create_qr_code({
  body = {
    title = "Campaign QR",
    destination = { bitlink_id = "bit.ly/abc123" },
  },
})

local webhooks = app.integrations.bitly.list_organization_webhooks({
  organization_guid = "org_guid",
})
```

## Generic API

```lua
local result = app.integrations.bitly.api_get({
  path = "/groups",
})
```

Generic write tools:

- `api_post({ path, body })`
- `api_patch({ path, body })`
- `api_delete({ path, body })`

Metadata-derived Lua example

local result = app.integrations.bitly.shorten_link({long_url = "example_long_url", domain = "example_domain", group_guid = "example_group_guid"})
print(result)

Functions

shorten_link Write

Shorten a long URL into a Bitlink. Returns the shortened URL and link details.

Lua path: app.integrations.bitly.shorten_link
Full name: bitly.bitly_shorten_link

Parameter	Type	Required	Description
`long_url`	string	yes	The long URL to shorten (e.g., "https://example.test/very/long/path").
`domain`	string	no	Custom short domain to use (e.g., "bit.ly", "j.mp"). Defaults to the account's default domain.
`group_guid`	string	no	The GUID of the group to associate this link with. If omitted, uses the default group.

get_link Read

Retrieve details for a Bitlink, including the long URL, title, tags, and timestamps.

Lua path: app.integrations.bitly.get_link
Full name: bitly.bitly_get_link

Parameter	Type	Required	Description
`bitlink`	string	yes	The Bitlink identifier (e.g., "bit.ly/abc123" or a full Bitly URL).

update_link Write

Update a Bitlink's metadata — set the title, archive/unarchive, or update tags.

Lua path: app.integrations.bitly.update_link
Full name: bitly.bitly_update_link

Parameter	Type	Required	Description
`bitlink`	string	yes	The Bitlink identifier (e.g., "bit.ly/abc123").
`title`	string	no	A descriptive title for the link.
`archived`	boolean	no	Whether to archive the link (true) or restore it (false).
`tags`	array	no	Array of tags to assign to the link (e.g., ["marketing", "campaign"]).

get_clicks Read

Get click metrics for a Bitlink. Returns click counts by time unit (minute, hour, day, week, month).

Lua path: app.integrations.bitly.get_clicks
Full name: bitly.bitly_get_clicks

Parameter	Type	Required	Description
`bitlink`	string	yes	The Bitlink identifier (e.g., "bit.ly/abc123").
`unit`	string	no	Time unit for click aggregation: "minute", "hour", "day", "week", or "month". Defaults to "day".
`units`	integer	no	Number of time units to return. Use -1 for all available data. Defaults to -1.
`unit_reference`	string	no	ISO 8601 timestamp for the reference point (e.g., "2026-01-01T00:00:00+0000").

get_click_summary Read

Get total click summary data for a Bitlink.

Lua path: app.integrations.bitly.get_click_summary
Full name: bitly.bitly_get_click_summary

Parameter	Type	Required	Description
`bitlink`	string	yes	Bitlink identifier.
`params`	object	no	Query parameters such as unit, units, and unit_reference.

get_click_countries Read

Get click counts grouped by country for a Bitlink.

Lua path: app.integrations.bitly.get_click_countries
Full name: bitly.bitly_get_click_countries

Parameter	Type	Required	Description
`bitlink`	string	yes	Bitlink identifier.
`params`	object	no	Query parameters such as unit, units, size, and unit_reference.

get_click_referrers Read

Get click counts grouped by referrer for a Bitlink.

Lua path: app.integrations.bitly.get_click_referrers
Full name: bitly.bitly_get_click_referrers

Parameter	Type	Required	Description
`bitlink`	string	yes	Bitlink identifier.
`params`	object	no	Query parameters such as unit, units, size, and unit_reference.

list_groups Read

List all groups in the Bitly account. Groups organize links and are used when creating new Bitlinks.

Lua path: app.integrations.bitly.list_groups
Full name: bitly.bitly_list_groups

Parameter	Type	Required	Description
No parameters.

get_group Read

Retrieve details for a specific Bitly group by its GUID.

Lua path: app.integrations.bitly.get_group
Full name: bitly.bitly_get_group

Parameter	Type	Required	Description
`group_guid`	string	yes	The GUID of the group to retrieve.

list_group_bitlinks Read

List Bitlinks in a Bitly group with optional filters.

Lua path: app.integrations.bitly.list_group_bitlinks
Full name: bitly.bitly_list_group_bitlinks

Parameter	Type	Required	Description
`group_guid`	string	yes	Bitly group GUID.
`params`	object	no	Query parameters such as size, page, keyword, query, and archived.

create_bitlink Write

Create a new Bitlink with title, tags, and optional custom domain. More full-featured than shorten — use this when you need metadata.

Lua path: app.integrations.bitly.create_bitlink
Full name: bitly.bitly_create_bitlink

Parameter	Type	Required	Description
`long_url`	string	yes	The destination URL to shorten.
`title`	string	no	A descriptive title for the link (e.g., "Q1 Marketing Campaign").
`tags`	array	no	Array of tags to categorize the link (e.g., ["marketing", "q1"]).
`domain`	string	no	Custom short domain (e.g., "bit.ly"). Defaults to account's default domain.
`group_guid`	string	no	The GUID of the group to associate this link with.

expand_bitlink Read

Expand a Bitlink to retrieve its long URL.

Lua path: app.integrations.bitly.expand_bitlink
Full name: bitly.bitly_expand_bitlink

Parameter	Type	Required	Description
`bitlink`	string	yes	Bitlink identifier such as bit.ly/abc123.

add_custom_bitlink Write

Add a custom back-half to an existing Bitlink on a custom domain.

Lua path: app.integrations.bitly.add_custom_bitlink
Full name: bitly.bitly_add_custom_bitlink

Parameter	Type	Required	Description
`custom_bitlink`	string	yes	Custom Bitlink such as example.test/campaign.
`bitlink_id`	string	yes	Existing Bitlink ID.

create_qr_code Write

Create a Bitly QR Code for a destination such as a Bitlink or long URL.

Lua path: app.integrations.bitly.create_qr_code
Full name: bitly.bitly_create_qr_code

Parameter	Type	Required	Description
`body`	object	yes	QR Code body accepted by Bitly, including destination and optional title/customization.

get_qr_code Read

Get a Bitly QR Code by ID.

Lua path: app.integrations.bitly.get_qr_code
Full name: bitly.bitly_get_qr_code

Parameter	Type	Required	Description
`qr_code_id`	string	yes	QR Code ID.

list_organization_webhooks Read

List webhooks for a Bitly organization.

Lua path: app.integrations.bitly.list_organization_webhooks
Full name: bitly.bitly_list_organization_webhooks

Parameter	Type	Required	Description
`organization_guid`	string	yes	Bitly organization GUID.

create_organization_webhook Write

Create a webhook for a Bitly organization.

Lua path: app.integrations.bitly.create_organization_webhook
Full name: bitly.bitly_create_organization_webhook

Parameter	Type	Required	Description
`organization_guid`	string	yes	Bitly organization GUID.
`body`	object	yes	Webhook body accepted by Bitly.

get_current_user Read

Get the authenticated Bitly user's profile. Use this to verify the connection and see account info.

Lua path: app.integrations.bitly.get_current_user
Full name: bitly.bitly_get_current_user

Parameter	Type	Required	Description
No parameters.

api_get Read

Call any Bitly API v4 GET endpoint.

Lua path: app.integrations.bitly.api_get
Full name: bitly.bitly_api_get

Parameter	Type	Required	Description
`path`	string	yes	API path such as /groups or /user.
`params`	object	no	Query parameters.

api_post Write

Call any Bitly API v4 POST endpoint.

Lua path: app.integrations.bitly.api_post
Full name: bitly.bitly_api_post

Parameter	Type	Required	Description
`path`	string	yes	API path.
`body`	object	no	JSON body.

api_patch Write

Call any Bitly API v4 PATCH endpoint.

Lua path: app.integrations.bitly.api_patch
Full name: bitly.bitly_api_patch

Parameter	Type	Required	Description
`path`	string	yes	API path.
`body`	object	no	JSON body.

api_delete Write

Call any Bitly API v4 DELETE endpoint.

Lua path: app.integrations.bitly.api_delete
Full name: bitly.bitly_api_delete

Parameter	Type	Required	Description
`path`	string	yes	API path.
`body`	object	no	JSON body.