# 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](/docs/api.md) 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](/docs/projects.md) and moves a service or a database between them. Moving restarts nothing. - `kilby env` changes the variables of one service; [`kilby env-group`](/docs/environment-groups.md) 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](/docs/services.md)). 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](/docs/log-streams.md), 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](/docs/webhooks.md#slack). 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](/docs/templates.md). A secret setting is never taken from a flag: `--set NAME` alone reads the environment variable `NAME`. ## Exit codes | Code | Meaning | |---|---| | 0 | Success. | | 1 | Anything else: the server said no, the network failed. | | 2 | Wrong flags or arguments, or a question that cannot be asked without a terminal. | | 3 | Not logged in, key refused (401) or not allowed to do this (403). | | 4 | The build failed, or it succeeded but the service did not go live. | | 5 | The build was canceled. | | 6 | Gave up waiting, or a request timed out. | | 7 | Not found: no such service, build or folder. | | 130 | Interrupted 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](/docs/agents.md). ## 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 [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 --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) ``` ## Related - [API keys and the API](/docs/api.md): the API the tool calls. - [Use Kilby from an AI agent](/docs/agents.md): `kilby mcp` and the safety model. - [Environment variables and secrets](/docs/environment.md): what `kilby env` changes. - [Troubleshooting](/docs/troubleshooting.md): when a command reports a failure.