Skip to the page
KilbyDocs
Automate View as Markdown
On this page

CLI

kilby is a command line tool for Kilby. It is one static program with no dependencies, it talks only to your Kilby server (and, when you run kilby update, to the address its releases are published at) and it has no telemetry. It uses the same REST API as everything else, so it can do what an API key's role allows.

Note

A downloadable build of kilby is not published yet. This page documents the tool as it is built from the Kilby source. If you only need to script Kilby, the REST API does everything the commands below do.

Log in#

sh
kilby login

kilby login asks for an API key (the input is hidden), checks it against the server and saves it. Create the key under API keys in the dashboard. There is one saved key per workspace, so you can be logged in to several workspaces and pick one with --workspace NAME.

  • A key is never accepted as a flag, because that would leave it in your shell history. Use the prompt, or kilby login --key-stdin in a script.
  • The server address must be https://, except for localhost. Change it with --url or KILBY_URL.
  • A saved key is bound to the server it was saved for. The tool refuses to send it anywhere else, and never follows a redirect.
  • In CI, skip login and set KILBY_API_KEY (and KILBY_URL). The environment wins over the saved login. Give CI a key with the smallest role that works: a Viewer key can look but not change.

Commands#

Every command accepts --json (print one JSON document and nothing else), --workspace NAME, --url URL and --no-color, before or after the command name, and --help. The list of commands, with the exact help of each, is at the end of this page: it is produced by running the tool.

sh
kilby whoami                       # which workspace, server and key role
kilby services                     # list the services
kilby services get api             # one service
kilby logs api --tail 100 -f       # what the service prints; -f follows
kilby env list api                 # names of the variables, never values
kilby env set api LOG_LEVEL=debug  # changing variables restarts the service
kilby rollback api --preview       # what a rollback would change; values are never shown
echo "$DB_PASSWORD" | kilby env set api DB_PASSWORD --stdin
kilby env import api .env
kilby secret-file put api .env ./.env   # a file the service reads at /etc/secrets/.env
kilby env-group create shared-keys OPENAI_API_KEY
kilby env-group link api shared-keys
echo "$SLACK_WEBHOOK_URL" | kilby slack add deploys --stdin   # send failures to a Slack channel
kilby slack test deploys
kilby templates                    # the gallery of ready-made apps
kilby templates deploy qdrant
kilby images check ghcr.io/acme/api:1.4   # does the image exist, and is it built for linux/amd64?
kilby open api --print             # print the service's address
kilby services delete old-prototype
sh
kilby databases create main --plan standard --storage 10   # a managed Postgres database
kilby databases info main                                   # status, address
sh
kilby kv create cache --plan 1gb   # a Key Value (Redis-compatible) instance
kilby kv info cache --connection

SERVICE is a name or an id. Output is compact; colours are used only on a terminal. Text that comes from a service (log lines) has its control characters removed before it is printed, so a log cannot drive your terminal.

  • kilby projects lists, creates and renames projects and environments and moves a service or a database between them. Moving restarts nothing.
  • kilby env changes the variables of one service; kilby env-group manages groups shared by several.
  • kilby images check IMAGE asks the image's registry whether it exists, as the dashboard does while you type (The image check). It exits with 1 when the image is certainly not usable, so CI can stop before a deploy; --credential NAME checks a private image with saved registry credentials.
  • kilby log-stream adds, tests and deletes log streams, which send a workspace's logs to a provider. The token is read from standard input or the environment, never from a flag.
  • kilby slack connects Slack channels for notifications. The webhook URL is a secret and is never taken from a flag: pipe it in with --stdin, set KILBY_SLACK_WEBHOOK_URL, or type it when asked.
  • kilby templates browses and deploys the templates. A secret setting is never taken from a flag: --set NAME alone reads the environment variable NAME.

Exit codes#

CodeMeaning
0Success.
1Anything else: the server said no, the network failed.
2Wrong flags or arguments, or a question that cannot be asked without a terminal.
3Not logged in, key refused (401) or not allowed to do this (403).
4The build failed, or it succeeded but the service did not go live.
5The build was canceled.
6Gave up waiting, or a request timed out.
7Not found: no such service, build or folder.
130Interrupted with Ctrl-C.

Errors go to standard error as one line. With --json they are a JSON object: {"error": {"message": "...", "hint": "...", "exit_code": 7}}.

MCP server#

kilby mcp runs a Model Context Protocol server so an AI agent can use Kilby. It is described in Use Kilby from an AI agent.

Help of every command#

This is what the tool prints for kilby help and for --help of each command. It is produced by running the tool, so it is always what the tool really says, and a command added to the tool shows up here.

text
kilby deploys code from GitHub to Kilby and runs your services.

Usage:
  kilby <command> [flags]

Commands:
  login      Save an API key for a workspace
  logout     Forget the saved key
  whoami     Show the workspace and server you are using
  deploy     Deploy the current Git repository
  services   List, show and delete services
  rollback   Roll a service back to an earlier deploy, after showing what changes
  databases  List, create, show and update managed Postgres databases
  kv         Create, show and delete Key Value (Redis-compatible) instances
  projects   Group services and databases into projects and environments
  slack      Send events to a Slack channel: add, test, list, remove
  templates  Deploy a ready-made AI app, database or tool
  images     Check that a container image exists before deploying it
  builds     List builds, read their logs, cancel, retry or fix them
  logs       Show the log of a running service
  metrics    Show a web service's request counts and latency
  env        List, set, unset and import environment variables
  env-group  Manage environment groups shared by services
  secret-file List, add and remove secret files (a .env file, a private key)
  log-stream Send logs to Datadog, syslog or another provider
  open       Open or print a service's URL
  mcp        Run an MCP server so AI agents can deploy
  version    Show the version
  update     Replace this program with the newest published build, after checking its signature

Get started:
  kilby login               save an API key (create one in the dashboard under API keys)
  cd my-repo && kilby deploy

Run 'kilby <command> --help' for the flags and examples of a command.

login#

text
Save an API key so the other commands can use it.

Usage:
  kilby login [--url URL] [--key-stdin]

Kilby checks the key against the server before saving it. The key is read from a
hidden prompt, or from standard input with --key-stdin. It is never accepted as a
flag: that would leave it in your shell history. It is saved in
~/.config/kilby/config.json (mode 0600), one key per workspace.

Flags:
  --key-stdin   Read the key from standard input (one line), for scripts

Examples:
  kilby login
  kilby login --url https://kilby.example.com
  echo "$KILBY_KEY" | kilby login --key-stdin

logout#

text
Forget the saved key of a workspace.

Usage:
  kilby logout [--workspace NAME] [--all]

This removes the key from this computer. It does not revoke it: do that in the
dashboard under API keys.

Flags:
  --all   Forget every saved workspace

Examples:
  kilby logout
  kilby logout --workspace acme-staging
  kilby logout --all

whoami#

text
Show which workspace and server the other commands use.

Usage:
  kilby whoami

It asks the server, so it also tells you whether the key still works.

Examples:
  kilby whoami
  kilby whoami --json

deploy#

text
Deploy a Git repository to Kilby and follow the build until the service is live.

Usage:
  kilby deploy [PATH] [flags]
  kilby deploy --git URL [--ref REF] [flags]

Run it inside a Git repository whose "origin" is on GitHub. Kilby builds what is on
GitHub, not your working directory: push first. The command finds which GitHub
connection of your workspace covers the repository, asks Kilby to detect how to build
and run it, shows you the plan, creates the service (or starts a build when it already
exists for that repository and branch), and shows each stage of the build with its
duration. Exit code 0 means the service went live; see the exit codes below.

Without a terminal, or with --yes, it never asks anything.

A PUBLIC repository needs no GitHub connection: kilby deploy --git https://github.com/owner/repo
(also gitlab.com and bitbucket.org) makes Kilby download the repository's archive and build it.
There is no push webhook for it, so run the command again (it builds only when the commit
changed), call the service's build hook from your CI, or turn on the check for new commits in
the dashboard. This works only where Kilby has deploying from Git switched on.

Flags:
  --git URL                Deploy a public repository by its https address, with no GitHub connection
  --ref REF                With --git: the branch, tag or commit (default: the repository's default branch)
  --repo OWNER/NAME        Deploy this repository instead of the one in the current directory
  --branch NAME            Branch to deploy (default: the branch you have checked out)
  --root DIR               Folder of a monorepo to deploy (default: the repository root)
  --name NAME              Service name (default: the repository name)
  --type TYPE              web, private or worker (default: what Kilby detects)
  --plan TYPE              Instance type: starter, standard or pro
  --port N                 Port the service listens on
  --dockerfile PATH        Build your own Dockerfile at this path (relative to the folder)
  --install-command CMD    Override the detected install command
  --build-command CMD      Override the detected build command ("" removes it)
  --start-command CMD      Override the detected start command
  --pre-deploy CMD         Command that runs once before each deploy, with the new version, such as
                           "python manage.py migrate" ("" removes it). If it fails the deploy fails and
                           the running version is not changed. It may run more than once for the same
                           version, so it must be safe to repeat
  --pre-deploy-timeout S   Seconds the pre-deploy command may run, 10 to 1800 (default 600)
  --env KEY=VALUE          Runtime variable (repeatable). Values are never printed
  --build-env NAME         Also make this variable available while building (repeatable);
                           its value comes from --env, or from your environment
  --environment ENV        Where to list a new service (an id, PROJECT/ENVIRONMENT or a name); see kilby projects
  --no-auto-deploy         Do not build on every push to the branch
  --installation ID        GitHub connection to use (default: found automatically)
  --yes, -y                Do not ask for confirmation
  --no-wait                Queue the build and return without following it
  --no-logs                Show the stages only; the log tail is shown if the build fails
  --timeout DURATION       Stop waiting after this long (default 30m)

Exit codes:
  0 live   1 error   2 usage   3 not logged in or not allowed   4 build failed
  5 build canceled   6 timed out   7 not found   130 interrupted (the build keeps running)

Examples:
  kilby deploy
  kilby deploy --yes --plan standard --env LOG_LEVEL=debug
  kilby deploy --repo acme/monorepo --root apps/api --name api
  kilby deploy --git https://github.com/render-examples/fastapi --ref main
  kilby deploy --env NEXT_PUBLIC_API_URL=https://api.example.com --build-env NEXT_PUBLIC_API_URL
  kilby deploy --json --yes > result.json

services#

text
List, show and delete services.

Usage:
  kilby services [list]
  kilby services get [SERVICE]
  kilby services delete SERVICE [--yes]

SERVICE is a name or an id. Inside a Git repository that has exactly one service,
SERVICE can be left out for get.

Flags:
  --yes, -y   Delete without asking you to type the name

Examples:
  kilby services
  kilby services get api
  kilby services delete old-prototype
  kilby services --json

rollback#

text
Roll a service back to an earlier deploy, after showing what would change.

Usage:
  kilby rollback [SERVICE] [DEPLOY] [--env=keep|restore] [--preview] [--yes]

A rollback deploys again what an earlier successful deploy ran: its image, start command, port or
schedule, instance type and health check path. The number of instances and the disk are kept.
Before anything happens the tool shows every setting that changes and the names of the environment
variables that would be added, removed or changed. Values are never shown.

Without DEPLOY the most recent successful deploy before the one that runs now is used. DEPLOY is
an id from kilby services get, or the first characters of one.

With --env=restore the service's variables become the ones that deploy ran with. They are then the
variables the service has saved: a redeploy, a deploy hook or a settings change keeps them. With
--env=keep the variables saved now stay. Without --env the variables are restored when the deploy
recorded them and they differ, and kept otherwise. A deploy that did not record its variables
cannot restore them.

Flags:
  --env MODE   keep or restore the environment variables (see above)
  --preview    Show what would change and do nothing
  --yes, -y    Roll back without asking (needed where there is no terminal)

Examples:
  kilby rollback api --preview
  kilby rollback api
  kilby rollback api 5d1e2b7c --env=keep --yes
  kilby rollback api --yes --json

databases#

text
List, create, show and update managed Postgres databases.

Usage:
  kilby databases [list]
  kilby databases create NAME [--plan starter|standard|pro] [--storage 1|5|10|20] [--version 17|18]
                              [--high-availability [--sync]]
  kilby databases info NAME
  kilby databases update NAME [--plan SIZE] [--storage GB] [--high-availability[=false]] [--sync[=false]]

NAME is a name or an id. A database is reached from the services of its workspace at
db-NAME-rw:5432 and from nowhere else. This command never prints its password: read the
connection URL in the dashboard.

Flags:
  --plan SIZE            Instance type: starter (default), standard or pro
  --storage GB           Disk size: 1, 5 (default), 10 or 20. A disk can grow, never shrink
  --version N            Postgres major version: 17 (default) or 18
  --high-availability    Run a standby on another node and fail over to it automatically. It
                         adds a second instance and a second disk. Turn it off with
                         --high-availability=false. Not available on every installation yet
  --sync                 With high availability: each commit waits for the standby, so a commit
                         you were told about survives a failover, and every write waits for a
                         network round trip. Without it the last few transactions can be lost

High availability protects against a node or a zone failing. It does not protect against a bad
migration or a dropped table, which the standby copies at once: use backups for that. A failover
takes tens of seconds.

Examples:
  kilby databases create main --plan standard --storage 10 --high-availability
  kilby databases update main --high-availability=false
  kilby databases info main

kv#

text
Create, list, show and delete Key Value instances (private Redis-compatible stores).

Usage:
  kilby kv [list]
  kilby kv create NAME [--plan 256mb|1gb|4gb] [--eviction allkeys-lru|noeviction] [--environment ENV]
  kilby kv info NAME [--connection]
  kilby kv delete NAME [--yes]

NAME is a name or an id. An instance is reached from the services of its workspace at
kv-NAME:6379 and from nowhere else. Its data is kept on a disk and survives restarts, but it is
NOT backed up: deleting the instance deletes the data.

Flags:
  --plan SIZE       Memory: 256mb (default), 1gb or 4gb
  --eviction POLICY What happens when memory is full: allkeys-lru removes the keys used least
                    recently (a cache, the default), noeviction refuses writes (a queue)
  --environment ENV With create: where to list it (an id, PROJECT/ENVIRONMENT or a name); see kilby projects
  --connection      With info: also print the connection URL, which includes the password
  --yes, -y         With delete: do not ask you to type the name

Examples:
  kilby kv create cache --plan 1gb
  kilby kv create jobs --eviction noeviction
  kilby kv info cache --connection
  kilby kv delete cache

projects#

text
Group the services, cron jobs, databases and Key Value instances of a workspace into
projects, each with environments such as Production and Staging.

Usage:
  kilby projects [list]
  kilby projects get PROJECT
  kilby projects create NAME
  kilby projects rename PROJECT NEW-NAME
  kilby projects delete PROJECT [--move-to ENVIRONMENT] [--yes]
  kilby projects environments PROJECT
  kilby projects add-environment PROJECT NAME
  kilby projects rename-environment PROJECT ENVIRONMENT NEW-NAME
  kilby projects delete-environment PROJECT ENVIRONMENT [--move-to ENVIRONMENT] [--yes]
  kilby projects move RESOURCE --environment ENVIRONMENT [--type service|database|kv]

This is organization, not isolation: every environment shares the workspace's limits,
members and network, and moving something to another environment restarts nothing. What
was never placed is in the Default project, in Production, which Kilby creates the first
time something needs it.

PROJECT is a name or an id. An ENVIRONMENT is an id, PROJECT/ENVIRONMENT, or just its
name when only one environment has it (names are compared without regard to capitals).
RESOURCE is the name or id of a service, a database or a Key Value instance.

Flags:
  --environment ENV  With move: where the resource goes. Also accepted by: kilby deploy,
                     kilby kv create
  --move-to ENV      With delete: where the resources go, when there are any
  --type KIND        With move: service, database or kv, when the name is used by more than one
  --yes, -y          With delete: do not ask you to type the name

Examples:
  kilby projects create "Checkout app"
  kilby projects add-environment "Checkout app" Staging
  kilby projects move api --environment "Checkout app/Staging"
  kilby projects delete "Checkout app" --move-to Default/Production

slack#

text
Send the events of the workspace to a Slack channel: connect one, test it, list them, remove one.

Usage:
  kilby slack [list]
  kilby slack add NAME [--channel LABEL] [--events EVENT,EVENT] [--stdin]
  kilby slack test NAME
  kilby slack rm NAME [--yes]

NAME is a name or an id. A channel is connected with an incoming webhook URL from Slack. That URL
is a secret: whoever has it can post in the channel. So it is never taken from a flag (it would end
up in your shell history and in the process list). Give it in one of three ways: pipe it in with
--stdin, export KILBY_SLACK_WEBHOOK_URL, or type it when asked (it is not shown). Kilby stores it
encrypted and never shows it again, not even to you: list shows only its host.

Flags:
  --channel LABEL   With add: the channel you are posting to, for example "#deploys". A label for you: the
                    message goes to the channel the webhook was created for
  --events LIST     With add: the events to send, comma separated (default: deploy.failed,cron.run.failed,
                    database.failed). The dashboard lists them all under Notifications
  --stdin           With add: read the webhook URL from standard input
  --yes, -y         With rm: do not ask for confirmation

Examples:
  echo "$SLACK_WEBHOOK" | kilby slack add deploys --channel "#deploys" --stdin
  kilby slack add ops --events deploy.failed,database.failed
  kilby slack test deploys
  kilby slack rm ops --yes

templates#

text
Browse the templates and deploy one: an open-source chat interface, a vector database, a workflow tool.

Usage:
  kilby templates [list]
  kilby templates get ID
  kilby templates deploy ID [--name NAME] [--name-for KEY=NAME] [--set NAME[=VALUE]]

A template creates ready-made services in your workspace: the image, the port, a disk and
the keys and passwords it needs, which Kilby generates and stores encrypted. They are
ordinary services afterwards. The same limits as for any new service apply, and a template
that does not fit is not deployed at all. Prices are the list price per month.

Flags:
  --name NAME         Name of the template's main service (default: the suggested name)
  --name-for KEY=NAME Name of another service of the template, by its key (see: templates get)
  --set NAME[=VALUE]  A setting the template asks for. Secrets are never taken from the flag:
                      --set NAME alone reads the environment variable NAME

Examples:
  kilby templates
  kilby templates get qdrant
  kilby templates deploy open-webui --name team-chat --set WEBUI_ADMIN_EMAIL=you@example.com
  kilby templates deploy open-webui-ollama --name team-chat --name-for ollama=team-models --set WEBUI_ADMIN_EMAIL=you@example.com
  OPENAI_API_KEY=... kilby templates deploy litellm --set OPENAI_API_KEY
  kilby templates deploy static-page --set PAGE_TITLE="Hello from CI"

images#

text
Check that a container image exists before you deploy it.

Usage:
  kilby images check IMAGE [--credential NAME]

Kilby asks the image's registry (Docker Hub, GHCR, Quay, GitLab, Amazon ECR Public, Google's
registries, or your own) for the tag or digest, and reads which platforms the image was built
for. Kilby's nodes run linux/amd64, so an image without that build is reported, with the
platforms it has. This is the check the dashboard runs while you type an image, and the one
that refuses to save a service whose image is not there.

A private image looks the same as one that does not exist unless you give credentials: name
registry credentials saved in your workspace with --credential (their name or id). They are
used on the server for this one check and never come back.

Exit code 0: the image was found, or Kilby could not tell (the registry did not answer, asked
for a login, or is limiting requests): nothing is refused in those cases. Exit code 1: the image
is certainly not usable (not found, credentials refused, or no linux/amd64 build).

Flags:
  --credential NAME   Saved registry credentials to check a private image with (name or id)

Examples:
  kilby images check ghcr.io/acme/api:1.4
  kilby images check nginx:1.27 --json
  kilby images check ghcr.io/acme/private-api:2 --credential github-acme
  kilby images check "$IMAGE" || exit 1

builds#

text
List the builds of a service, read their logs, and cancel, retry or fix them.

Usage:
  kilby builds [list] [SERVICE] [--limit N]
  kilby builds get [SERVICE] [BUILD]
  kilby builds logs [SERVICE] [BUILD] [-f] [--tail N]
  kilby builds cancel [SERVICE] [BUILD]
  kilby builds retry [SERVICE] [BUILD] [--no-wait]
  kilby builds fix [SERVICE] [BUILD] [--apply N]

BUILD is a build number (4) or id; it defaults to the latest build. SERVICE can be
left out inside a Git repository that has exactly one service.

"fix" shows the suggestions of a failed build's diagnosis. With --apply N it applies
suggestion N to the service's settings and starts a new build, which it follows.

Flags:
  --limit N        Builds to list (default 20, at most 100)
  -f, --follow     Keep reading the log until the build ends
  --tail N         Show only the last N lines of the log (default: all)
  --apply N        Apply suggested fix number N
  --no-wait        Do not follow the new build
  --timeout DURATION   Stop following after this long (default 30m)

Examples:
  kilby builds api
  kilby builds logs api 4 -f
  kilby builds get api --json
  kilby builds retry api
  kilby builds fix api 4 --apply 1

logs#

text
Show the log of a service (what your program prints).

Usage:
  kilby logs [SERVICE] [--tail N] [-f]
  kilby logs [SERVICE] [--since TIME] [--until TIME] [--grep TEXT] [--level LEVEL] [--limit N]

Without the second set of flags this reads the live output of the running instances.
With any of them it reads the stored log (when your Kilby keeps logs), including what
instances that crashed or were replaced printed. Lines are printed oldest first.

For the log of a build, use: kilby builds logs.

Flags:
  --tail N        Live: number of lines (default 200, at most 2000)
  -f, --follow    Live: keep printing new lines (polls every few seconds)
  --since TIME    Stored: start of the range, a time (2026-11-14T10:00:00Z) or how long ago (15m, 1h, 7d). Default 1h
  --until TIME    Stored: end of the range (default now)
  --grep TEXT     Stored: only lines that contain TEXT, ignoring case
  --level LEVEL   Stored: only error, warn, info or debug lines (a comma separated list works), as guessed from the text
  --limit N       Stored: at most N lines, the newest in the range (default 200, at most 5000)

Examples:
  kilby logs api
  kilby logs api --tail 50 -f
  kilby logs api --since 1h --grep timeout
  kilby logs api --since 2026-11-14T03:00:00Z --until 2026-11-14T03:30:00Z --level error

metrics#

text
Show how much traffic a web service served and how it went.

Usage:
  kilby metrics requests [SERVICE] [--range 1h|6h|24h|7d|30d]

Kilby counts the requests that reach a web service through its proxy: how many, how
many failed with a 5xx error, and how long the service took to answer. A latency
percentile needs enough requests (20, and 100 for the 99th): below that it shows
"not enough requests". Only web services have request metrics. Without SERVICE the
service that deploys this Git repository is used.

Flags:
  --range R   How far back to look: 1h (default), 6h, 24h, 7d or 30d

Examples:
  kilby metrics requests api
  kilby metrics requests api --range 24h
  kilby metrics requests api --range 30d --json

env#

text
List, set, unset and import the environment variables of a service.

Usage:
  kilby env [list] [SERVICE]
  kilby env set [SERVICE] NAME=VALUE [NAME=VALUE ...]
  kilby env set [SERVICE] NAME            (value read from your environment, or asked for)
  kilby env set [SERVICE] NAME --stdin    (value read from standard input)
  kilby env unset [SERVICE] NAME [NAME ...]
  kilby env import [SERVICE] FILE [--replace]

Values are never printed, and cannot be read back: Kilby only ever shows names.
Prefer "NAME" or "--stdin" over NAME=VALUE for secrets: a value on the command line
is visible in your shell history and to other users of the machine.

Changing the variables of a running service restarts it. With --build the commands
work on the variables available to builds instead of the runtime variables.

"import" reads a .env file (KEY=VALUE lines, # comments, quotes, "export KEY=...").
Values are not expanded: $OTHER stays as written. With --replace the file becomes the
complete set of variables, removing the others.

Flags:
  --build      Work on build variables instead of runtime variables
  --stdin      Read the value of the one NAME from standard input
  --replace    import: replace all variables with the ones in the file
  --yes, -y    import --replace: do not ask for confirmation

Examples:
  kilby env list api
  kilby env set api LOG_LEVEL=debug
  echo "$DB_PASSWORD" | kilby env set api DB_PASSWORD --stdin
  kilby env unset api OLD_FLAG
  kilby env import api .env

env-group#

text
Manage environment groups: variables defined once and linked to several services.

Usage:
  kilby env-group list
  kilby env-group create NAME [NAME=VALUE ...]
  kilby env-group set GROUP NAME=VALUE [NAME=VALUE ...]
  kilby env-group set GROUP NAME            (value read from your environment, or asked for)
  kilby env-group set GROUP NAME --stdin    (value read from standard input)
  kilby env-group unset GROUP NAME [NAME ...]
  kilby env-group link [SERVICE] GROUP [GROUP ...] [--first]
  kilby env-group unlink [SERVICE] GROUP [GROUP ...]
  kilby env-group delete GROUP [--unlink] [--yes]

A service gets its own variables plus those of every group it uses. If a name is in more
than one place, the service's own variable wins, then the group linked first. New links go
last, so the groups already there keep winning; --first puts them in front.

Changing a group restarts every service that uses it, once each. Linking and unlinking
restarts the service once. Values are never printed and cannot be read back.

A group that services use is deleted only with --unlink: they are unlinked and restart
without its variables.

Flags:
  --stdin      set: read the value of the one NAME from standard input
  --first      link: put the groups before the ones already linked
  --unlink     delete: delete a group that services use, unlinking them
  --yes, -y    delete --unlink: do not ask for confirmation

Examples:
  kilby env-group create shared-keys OPENAI_API_KEY
  kilby env-group link api shared-keys
  echo "$SENTRY_DSN" | kilby env-group set shared-keys SENTRY_DSN --stdin
  kilby env-group delete old-keys --unlink --yes

secret-file#

text
Manage the secret files of a service: plaintext files with secret data, such as a .env file or a private key.

Usage:
  kilby secret-file list [SERVICE]
  kilby secret-file put [SERVICE] NAME [FILE]   (FILE is a local file; - reads standard input)
  kilby secret-file rm [SERVICE] NAME [--yes]

The service reads each file at /etc/secrets/NAME, read-only. Kilby does not copy the files into
the service's working directory. NAME is a plain file name (letters, digits, dots, underscores and
hyphens), not a path. With no FILE, put reads the local file called NAME.

The content is stored encrypted and is never printed or listed back: list shows names and sizes.
Adding, replacing or removing a file restarts the service once (a cron job takes the change from
its next run). A service with a disk is down for a short time while it restarts. Putting the same
content again changes nothing.

A file is text, up to 128 KB by default; a service holds ten by default.

Flags:
  --yes, -y    rm: do not ask for confirmation

Examples:
  kilby secret-file put api .env ./.env
  kilby secret-file put api private-key.pem ~/keys/api.pem
  echo "$TOKEN_FILE" | kilby secret-file put api token.txt -
  kilby secret-file list api
  kilby secret-file rm api private-key.pem --yes

log-stream#

text
Send the logs of your services to a provider you use: Datadog, an HTTPS endpoint,
syslog over TLS, Grafana Loki or Better Stack. Needs log storage to be on.

Usage:
  kilby log-stream list
  kilby log-stream add NAME --kind KIND [flags]
  kilby log-stream test NAME
  kilby log-stream rm NAME [--yes]

The token or API key is never an argument: pipe it in with --token-stdin, export
KILBY_LOG_STREAM_TOKEN, or type it when asked (hidden). It is stored encrypted and never shown
again, only its last four characters. A log stream that keeps failing is turned off and the
owners and admins of the workspace get an email. Adding, testing and deleting need an admin key.

Flags for add:
  --kind KIND          datadog, https, syslog, loki or betterstack
  --site SITE          datadog: us1, us3, us5, eu1 or ap1
  --tags TAGS          datadog: comma separated, for example env:prod,team:ai
  --endpoint ADDRESS   https, loki, betterstack: an https URL. syslog: host:port
  --header NAME        https: send the token in this header instead of Authorization: Bearer
  --format FORMAT      https: ndjson (one JSON object per line) or json (one array)
  --gzip               https: compress the body
  --facility NAME      syslog: user, daemon or local0 to local7
  --user NAME          loki: user name (the token is then the password)
  --skip-tls-verify    do not check the certificate (the connection stays encrypted)
  --service A,B        only these services (names or ids); every service when left out
  --level LEVEL        the lowest level sent: debug, info, warn or error
  --token-stdin        read the token from standard input
  --yes, -y            rm: do not ask for confirmation

Examples:
  echo "$DD_API_KEY" | kilby log-stream add prod-datadog --kind datadog --site eu1 --token-stdin
  kilby log-stream add sink --kind https --endpoint https://logs.example.com/ingest --level warn
  kilby log-stream add papertrail --kind syslog --endpoint logs.example.com:6514
  kilby log-stream test prod-datadog

open#

text
Open a service's URL in your browser, or print it.

Usage:
  kilby open [SERVICE] [--print] [--dashboard]

Without a terminal, or with --print, the address is printed instead of opened.

Flags:
  --print       Print the address, do not open it
  --dashboard   The service's page in the dashboard instead of the service itself

Examples:
  kilby open api
  kilby open api --dashboard
  curl "$(kilby open api --print)/healthz"

mcp#

text
Run an MCP server on standard input and output, so an AI agent can deploy for you.

Usage:
  kilby mcp [--read-only]

The server speaks the Model Context Protocol (revision 2025-06-18) as newline-delimited
JSON-RPC 2.0 over stdio. It uses your saved login or KILBY_API_KEY and can do exactly
what that key's role allows. Nothing but protocol messages is written to standard
output; diagnostics go to standard error.

Flags:
  --read-only   Offer only the tools that read: no deploys, builds, cancels or variable changes

Examples:
  claude mcp add kilby -- kilby mcp
  claude mcp add kilby-readonly -- kilby mcp --read-only

version#

text
Show the version of this tool.

Usage:
  kilby version

Examples:
  kilby version
  kilby version --json

update#

text
Replace this program with the newest published build of kilby.

The release's list of SHA-256 checksums must carry a valid signature from the Kilby release key,
which is built into this program, and the download must match that list. Only then is the file
swapped, in one step. A program built from the source cannot update itself.

Usage:
  kilby update [--check] [--version X.Y.Z]

Flags:
  --check            Only say whether a newer version is published
  --version X.Y.Z    Install this version instead of the newest (also to go back)

Environment:
  KILBY_RELEASE_URL  Download from this address instead of the one built in (a mirror); the
                     signature is still checked against the built-in key

Examples:
  kilby update --check
  kilby update
  kilby update --version 1.4.0

All commands also share:

text
Global flags (work with every command, before or after its name):
  --json             Print machine-readable JSON instead of text
  --workspace NAME   Use the saved login of this workspace
  --url URL          Use this Kilby server (https; http only for localhost)
  --no-color         Never use colour (also: NO_COLOR=1)

Environment:
  KILBY_API_KEY      API key to use instead of the saved login (for CI)
  KILBY_URL          Server to use (default https://onkilby.com)