This is the abridged developer documentation for kinstactl # kinstactl > Everything the Kinsta API can do, from your terminal: sites and environments by name, backups, cache, pushes, logs, and a typed client for your own scripts. ```sh kinstactl sites list kinstactl cache clear my-site --env live kinstactl backups create my-site --env live ``` # Authentication > Log in with a Kinsta API key, or provide credentials through environment variables. kinstactl needs a Kinsta API key and the ID of your company. `auth login` stores both for you. ```sh kinstactl auth login ``` The command prompts for the API key without echoing it, validates it against the Kinsta API (`GET /validate`), and stores the key together with the company ID that Kinsta reports for it. You never type the company ID yourself. Create the key in MyKinsta, in your company’s API key settings. ## Reading the key from stdin [Section titled “Reading the key from stdin”](#reading-the-key-from-stdin) A key passed as `--api-key ` ends up in your shell history. Pass `-` to read it from stdin instead, which is also the way to log in without a terminal: ```sh kinstactl auth login --api-key - < key.txt ``` Without a terminal and without `--api-key`, the command fails with a `USAGE` error rather than waiting for input. ## Checking and removing a login [Section titled “Checking and removing a login”](#checking-and-removing-a-login) ```sh kinstactl auth status kinstactl auth logout ``` `auth status` shows where the credentials come from (`env` or `profile`), the company ID, the key name, its status and when it expires. It validates the key against Kinsta, so it fails when the key is revoked. `auth logout` removes the stored profile. Neither command ever prints the key itself. ## Environment variables [Section titled “Environment variables”](#environment-variables) For CI and containers, export the credentials instead of logging in: ```sh export KINSTA_API_KEY= KINSTA_COMPANY_ID= ``` Both variables are required together. Setting only one fails with `AUTH_MISSING`. They win over the config file, unless you pass `--profile`, which always selects a stored profile (see [Profiles](/getting-started/profiles/)). ## Where the key is stored [Section titled “Where the key is stored”](#where-the-key-is-stored) `auth login` writes `~/.config/kinstactl/config.json`, or `$XDG_CONFIG_HOME/kinstactl/config.json` when `XDG_CONFIG_HOME` is set. The file is created with mode `0600`, so only your user can read it. The API key is stored in it in plain text. # Installation > Install kinstactl from npm, as a standalone binary or as a Docker image. kinstactl ships as an npm package, as standalone binaries and as a Docker image. They all run the same CLI. ```sh npm i -g kinstactl npx kinstactl --version ``` ## npm [Section titled “npm”](#npm) The package needs Node.js 22.12 or newer. Install it globally to get the `kinstactl` command, or run it once with `npx` without installing anything. ## Binaries [Section titled “Binaries”](#binaries) Every [release](https://github.com/rickklaasboer/kinstactl/releases) has a binary per platform, so you can run kinstactl without Node.js: * `kinstactl-darwin-arm64` * `kinstactl-darwin-x64` * `kinstactl-linux-x64` * `kinstactl-linux-arm64` * `kinstactl-windows-x64.exe` Each release also has a `SHA256SUMS` file. Verify the download before you run it. `--ignore-missing` skips the files you did not download. ```sh shasum -a 256 -c --ignore-missing SHA256SUMS && chmod +x kinstactl-darwin-arm64 && ./kinstactl-darwin-arm64 --version ``` On Linux, use `sha256sum` instead of `shasum -a 256` and the `kinstactl-linux-x64` file name. macOS quarantines a binary that you download through a browser. Clear the flag, or download with `curl -LO` instead: ```sh xattr -d com.apple.quarantine kinstactl-darwin-arm64 ``` The `darwin-x64` binary (Intel Macs) is built and attached to each release, but CI does not smoke-test it. Like the npm package, the binaries do not load a `.env` file or a `bunfig.toml` from the working directory. Credentials come from [`kinstactl auth login`](/getting-started/authentication/) or from exported environment variables. ## Docker [Section titled “Docker”](#docker) The image is based on the linux-x64 binary, so it is `linux/amd64` only. It has no entrypoint: pass the command to run. ```sh docker run --rm -e KINSTA_API_KEY -e KINSTA_COMPANY_ID ghcr.io/rickklaasboer/kinstactl kinstactl sites list ``` In GitLab CI, use it as the job image: ```yaml list-sites: image: ghcr.io/rickklaasboer/kinstactl script: kinstactl sites list ``` Provide `KINSTA_API_KEY` and `KINSTA_COMPANY_ID` as masked CI/CD variables. # Profiles > Store the credentials of several companies and switch between them. A profile is a named set of credentials. Use one per company when you work with more than one. ```sh kinstactl auth login --profile work kinstactl auth profiles kinstactl sites list --profile work ``` `auth login --profile ` stores the key under that name. `auth profiles` lists the stored profiles with their company ID, key name and which one is the default. `--profile` is a global flag, so it works on every command. ## Which profile is used [Section titled “Which profile is used”](#which-profile-is-used) kinstactl picks the profile in this order: 1. the `--profile` flag 2. the `KINSTA_PROFILE` environment variable 3. the `defaultProfile` in the config file 4. a profile named `default` The first `auth login` sets `defaultProfile` to the profile it stores, so later logins under another name do not change which one is the default. `auth logout` removes the selected profile by the same rules, and clears `defaultProfile` when it pointed at it. ```sh KINSTA_PROFILE=work kinstactl sites list ``` An unknown profile name fails with `AUTH_MISSING` and lists the profiles that exist. With a single company you never need any of this: `auth login` without `--profile` stores a profile called `default`, and every command uses it. # Sites and environments > Refer to sites and environments by name, display name or ID. Commands take a `` argument and, for environment-specific actions, an `--env ` flag. You use names; kinstactl looks up the IDs. ```sh kinstactl cache clear my-site --env live ``` ## Sites [Section titled “Sites”](#sites) `` accepts the site name, its display name or its ID. kinstactl matches exactly first, ignoring case. When nothing matches exactly, it accepts a prefix, as long as the prefix identifies one site. * No match fails with `SITE_NOT_FOUND`. The `hints` of the error list the closest site names. * A prefix that matches several sites fails with `SITE_AMBIGUOUS`, and the `hints` list the candidates. Without ``, a command on a terminal shows a searchable picker. In a script, `--no-input` or CI it fails with a `USAGE` error instead. ## Environments [Section titled “Environments”](#environments) `--env ` accepts the same three forms as a site: name, display name or ID, exact first and then an unambiguous prefix. When you leave `--env` out: * A site with one environment uses that one, and kinstactl says so. * On a terminal, you get a picker with the live environment first. * In a script, the command fails with `ENV_REQUIRED`, and the `hints` list one `--env ` suggestion per environment. Pass `--env` explicitly in scripts, so a command never depends on whether a terminal is attached. ## The site cache [Section titled “The site cache”](#the-site-cache) Looking up a name needs the list of your sites. kinstactl caches that list for five minutes in `~/.cache/kinstactl`, or in `$XDG_CACHE_HOME/kinstactl` when `XDG_CACHE_HOME` is set, with one file per company. ```sh kinstactl sites list --refresh ``` `--refresh` bypasses the cache and rewrites it. Commands that change something always resolve the site against fresh data, so a stale cache can never point a write at the wrong site. ## Shell completion [Section titled “Shell completion”](#shell-completion) Site and environment names complete in your shell once you install the completion script, for example `eval "$(kinstactl completion bash)"`. See [completion](/commands/completion/) for bash, zsh and fish. # For agents > Give a coding agent a prompt and a skill so it can operate Kinsta through kinstactl safely. Coding agents can run kinstactl without a terminal session. This page has the prompt to hand them and a skill file that carries the same text. ## Why the CLI is agent-safe [Section titled “Why the CLI is agent-safe”](#why-the-cli-is-agent-safe) * Without a TTY the CLI never prompts. With `--no-input` it fails instead of asking. * Errors are JSON on stderr with a `code`, a `message` and `hints` that say what to do next. * Every write supports `--dry-run`, which prints the resolved target and request and changes nothing. * Irreversible actions need `--confirm `, so an agent cannot trigger them by accident. * `kinstactl commands --json` lists every command, argument, flag and the API endpoints it calls. * The docs are published as plain text in [llms.txt](/llms.txt). ## The prompt [Section titled “The prompt”](#the-prompt) Paste this into your agent’s instructions. Use the copy button in the corner of the block. Prompt for your agent ```text You operate Kinsta hosting through the command line client kinstactl. Follow these rules. Install - Install the CLI with npm i -g kinstactl, or run it without installing through npx kinstactl. - Verify the install: kinstactl --version Authenticate - Credentials come from the KINSTA_API_KEY and KINSTA_COMPANY_ID environment variables, or from an existing profile (select one with --profile ). - Never print, log or echo the API key, and never put it in a command line, a file or a commit. Discover - List every command with its arguments, flags and the API endpoints it calls: kinstactl commands --json - Read the details of one command with its --help, for example: kinstactl sites delete --help Run commands - Always pass --json --no-input. Output is then machine-readable and the CLI fails instead of prompting. - On a non-zero exit, parse the error object on stderr. It has code, message and hints. Act on hints before you retry or give up. Make changes safely - Run every write first with --dry-run, and show the human what will change: kinstactl sites delete my-site --dry-run --json --no-input - After you show the dry run, wait for the human's go-ahead before you run the write itself, whatever its confirmation level. - Never pass --yes or --confirm without the human's explicit approval for that specific action. Approval for one action is not approval for the next. - --confirm exists only for irreversible actions, and takes the exact site name. - Treat passwords, login links and tokens that commands print (ssh password get, wp login, db login) like the API key: never log, echo or store them, and show them to the human only when that was the point of the request. Long operations - Prefer --no-wait. With --json the response has an operation_id; read it from the JSON, then wait for it: kinstactl operations wait --json --no-input - Use --timeout on the wait if the default of 30 is too short or too long. Documentation - The docs are at https://kinstactl.rickklaasboer.nl - A plain-text version for agents is at https://kinstactl.rickklaasboer.nl/llms.txt ``` ## Install as a skill [Section titled “Install as a skill”](#install-as-a-skill) The prompt is the body of a Claude Code skill. Install it once and the agent loads it when you ask for Kinsta work: ```sh mkdir -p ~/.claude/skills/kinstactl && curl -fsSL https://raw.githubusercontent.com/rickklaasboer/kinstactl/main/skills/kinstactl/SKILL.md -o ~/.claude/skills/kinstactl/SKILL.md ``` ## llms.txt [Section titled “llms.txt”](#llmstxt) The site publishes three files for language models: * [llms.txt](https://kinstactl.rickklaasboer.nl/llms.txt): an index that links to the two sets below and to a command reference (every command with its arguments, flags and the Kinsta API endpoints it calls). * [llms-small.txt](https://kinstactl.rickklaasboer.nl/llms-small.txt): the docs in condensed form. * [llms-full.txt](https://kinstactl.rickklaasboer.nl/llms-full.txt): the complete docs in one file. ## Not an MCP server [Section titled “Not an MCP server”](#not-an-mcp-server) kinstactl is a CLI, not an MCP server; the typed client in the package makes it cheap to add one later. # Scripting and CI > Run kinstactl from scripts and CI pipelines with JSON output, no prompts, dry runs, exit codes and environment variables. kinstactl is built to be called from scripts. Output is machine-readable on demand, nothing prompts when no one is there to answer, and every failure has a stable code and exit status. ## Machine-readable output [Section titled “Machine-readable output”](#machine-readable-output) Pass `--json` to get JSON on stdout. ```sh kinstactl sites list --json | jq -r '.[].name' ``` With `--json`, stdout holds only the result document. Human messages such as progress lines and hints go to stderr, and are left out entirely in JSON mode, so `stdout` is always safe to pipe into `jq`. Errors are printed to stderr as JSON too; see [Exit codes and the error object](#exit-codes-and-the-error-object). The JSON shapes are documented per command and kept stable. Changing a field name or removing one is a breaking change and ships as one. To discover every command, argument and flag programmatically, ask kinstactl itself: ```sh kinstactl commands --json ``` ## No prompts [Section titled “No prompts”](#no-prompts) A script must never wait for input. kinstactl prompts only when stdin and stdout are both a terminal, and not when any of these is true: * you pass `--json`, * you pass the global `--no-input` flag, * `KINSTACTL_NO_INPUT=1` is set, * `CI=true` is set (most CI systems set it). ```sh kinstactl backups create my-site --env live --no-input ``` When a command would have prompted, it fails instead, with the code that names what is missing. Pass every value a prompt would have asked for: * `--env ` is required when the site has more than one environment, otherwise the command fails with `ENV_REQUIRED`. A site with a single environment uses it without `--env`, but pass it anyway so the script keeps working when a second environment appears. * A missing `` argument fails with a `USAGE` error. * `auth login` needs `--api-key ` (or `--api-key -` for stdin) and fails with `USAGE` without it. * Confirmations are covered in the next section. kinstactl prints colour only on a terminal. Set `NO_COLOR=1` to turn it off there as well. ## Confirmations [Section titled “Confirmations”](#confirmations) Destructive commands ask before they act. In a script you answer in advance with a flag. ```sh kinstactl backups restore my-site 123456789 --env live --notify admin@example.com --yes kinstactl sites delete my-site --confirm my-site ``` Two levels exist, and `kinstactl --help` shows which flag a command takes: * `--yes` skips the confirmation of a command that is destructive but recoverable, such as `backups restore`. * `--confirm ` is required for irreversible commands, such as `sites delete`. `--yes` is deliberately not accepted there: you pass the name of the site, so a copy-pasted command cannot delete the wrong one. Without the flag, and without a terminal, the command fails with `CONFIRMATION_REQUIRED` (exit 5). A `--confirm` value that does not match the site also gives `CONFIRMATION_REQUIRED`. On a terminal, answering no gives `CONFIRMATION_DECLINED`, also exit 5. ## Dry runs [Section titled “Dry runs”](#dry-runs) `--dry-run` resolves everything and prints what would be sent, without sending it. ```sh kinstactl cache clear my-site --env live --dry-run --json ``` Every command that changes something takes `--dry-run`. The output is a single document: ```json { "dry_run": true, "target": { "site": {"id": "", "name": "my-site"}, "env": {"id": "", "name": "live"} }, "request": { "method": "POST", "path": "/sites/tools/clear-cache", "body": {"environment_id": ""} } } ``` `target` holds the resolved site and environment, and `request` the HTTP method, path, query and body. Secrets in the body, such as passwords and API keys, are redacted. A dry run happens before the confirmation, so it never asks for `--yes` or `--confirm`. Use it to check that a script points at the right site and environment before you let it run for real. ## Long operations [Section titled “Long operations”](#long-operations) Many commands start a Kinsta operation and wait for it to finish. In a script, you can start it and come back later. ```sh kinstactl backups create my-site --env live --no-wait --json kinstactl operations wait --timeout 10 ``` With `--json`, `--no-wait` prints `{"operation_id": "...", "status": "pending"}` on stdout. Without `--json` it prints a `Started ...` line on stdout and the operation ID only in the `Follow with: kinstactl operations wait ` hint on stderr, so use `--json` when a script has to capture the ID. Not every write command takes `--no-wait`. Commands that finish immediately, such as `ssh enable` or `security redirects add`, have no operation to wait for; `kinstactl --help` lists the flags. `operations wait` and the waiting commands take `--timeout ` (default 30). A failed operation exits with code 3 (`OPERATION_FAILED`). A wait that ends before the operation does exits with code 4 (`OPERATION_TIMEOUT`); the operation may still complete on Kinsta’s side, so check it with `kinstactl operations get ` instead of starting it again. ## Environment variables [Section titled “Environment variables”](#environment-variables) | Variable | Meaning | | -------------------- | -------------------------------------------------------------------------------- | | `KINSTA_API_KEY` | The Kinsta API key. Set it together with `KINSTA_COMPANY_ID`. | | `KINSTA_COMPANY_ID` | The ID of your company. Set it together with `KINSTA_API_KEY`. | | `KINSTA_PROFILE` | The stored profile to use when `--profile` is not given. | | `KINSTACTL_NO_INPUT` | Set to `1` to never prompt, like `--no-input`. | | `KINSTACTL_DEBUG` | Set to `1` to add the stack trace of unexpected errors to the JSON error object. | | `CI` | When `true`, kinstactl never prompts, like `--no-input`. | | `NO_COLOR` | Set to a non-empty value to turn off colour. | | `XDG_CONFIG_HOME` | Base directory of the config file, `~/.config` by default. | | `XDG_CACHE_HOME` | Base directory of the site cache, `~/.cache` by default. | `KINSTA_API_KEY` and `KINSTA_COMPANY_ID` win over the config file; see [Authentication](/getting-started/authentication/). `--profile` always selects a stored profile instead. ## Exit codes and the error object [Section titled “Exit codes and the error object”](#exit-codes-and-the-error-object) Every failure has a code, and the code decides the exit status. | Code | Exit | Meaning | | ----------------------- | ---- | ------------------------------------------------------------------------------------- | | `USAGE` | 2 | Unknown command or flag, or a required argument or value is missing. | | `AUTH_MISSING` | 2 | No credentials found, or only one of `KINSTA_API_KEY` and `KINSTA_COMPANY_ID` is set. | | `SITE_NOT_FOUND` | 2 | No site matches the name you gave. | | `SITE_AMBIGUOUS` | 2 | The name matches more than one site. | | `ENV_REQUIRED` | 2 | The site has several environments and `--env` was not given. | | `ENV_NOT_FOUND` | 2 | The site has no environment with that name, or the name matches several. | | `API_ERROR` | 1 | The Kinsta API rejected the request, or could not be reached. | | `INTERNAL` | 1 | An unexpected error in kinstactl itself. | | `AUTH_INVALID` | 1 | Kinsta rejected the API key (HTTP 401). | | `OPERATION_FAILED` | 3 | A Kinsta operation ended in failure. | | `OPERATION_TIMEOUT` | 4 | The wait for an operation ran out, or contact with Kinsta was lost while waiting. | | `CONFIRMATION_REQUIRED` | 5 | A destructive command needs `--yes` or `--confirm `. | | `CONFIRMATION_DECLINED` | 5 | The confirmation was answered with no. | A successful run exits 0. With `--json`, the error is a single object on stderr: ```json { "error": { "code": "ENV_REQUIRED", "message": "Site my-site has several environments; choose one", "hints": ["--env live", "--env staging"] } } ``` `code` is stable and meant for scripts. `message` is for people and may change. `hints` lists suggested fixes and is empty when there are none. Set `KINSTACTL_DEBUG=1` to add a `stack` field to `INTERNAL` errors. ## A GitHub Actions example [Section titled “A GitHub Actions example”](#a-github-actions-example) Store the credentials as repository secrets and install kinstactl from npm. ```yaml name: backup on: schedule: - cron: '0 3 * * *' jobs: backup: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - run: npm i -g kinstactl - run: kinstactl backups create my-site --env live --json --no-input env: KINSTA_API_KEY: ${{ secrets.KINSTA_API_KEY }} KINSTA_COMPANY_ID: ${{ secrets.KINSTA_COMPANY_ID }} ``` GitHub sets `CI=true`, so the `--no-input` flag is redundant there, but it states the intent and keeps the same command working elsewhere. A non-zero exit fails the step. The job waits for the backup to finish; add `--no-wait` to start it and move on. In GitLab CI, use the Docker image, which has no entrypoint: ```yaml list-sites: image: ghcr.io/rickklaasboer/kinstactl script: kinstactl sites list ``` `KINSTA_API_KEY` and `KINSTA_COMPANY_ID` come from masked CI/CD variables. # analytics > Traffic, bandwidth, disk space and bot protection analytics of an environment. The `analytics` command shows one metric of an environment over a period of time. ```sh kinstactl analytics visits my-site --env live kinstactl analytics top-countries my-site --env live --span 30d kinstactl analytics bot-traffic-flow my-site --env live --json ``` Without `--env`, a site with one environment uses it; a site with several gets a picker on a terminal and fails with `ENV_REQUIRED` in a script. See [Sites and environments](/getting-started/sites-and-environments/). The command only reads, so it has no `--dry-run`, `--no-wait` or confirmation. ## analytics [Section titled “analytics”](#analytics) Show one analytics metric of an environment. ```sh kinstactl analytics visits my-site --env live --span 30d ``` ```sh kinstactl analytics [site] [options] ``` Traffic, bandwidth, disk and bot analytics of an environment #### Arguments | Argument | Description | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `metric` | metric: visits, bandwidth, cdn-bandwidth, diskspace, top-countries, top-cities, top-ips, top-asns, top-browsers, top-hosts, top-referrers, top-user-agents, visits-dispersion, response-codes, bot-traffic-flow, bot-requests, bot-protection-results, bot-top-breakdown Choices: `visits`, `bandwidth`, `cdn-bandwidth`, `diskspace`, `top-countries`, `top-cities`, `top-ips`, `top-asns`, `top-browsers`, `top-hosts`, `top-referrers`, `top-user-agents`, `visits-dispersion`, `response-codes`, `bot-traffic-flow`, `bot-requests`, `bot-protection-results`, `bot-top-breakdown`. | | `site` | site name, display name or ID | #### Options | Option | Description | | ---------------------- | --------------------------------------------------------------- | | `--env ` | environment name or ID | | `--span ` | time span: 24h, 7d, 30d, 60d (default: 7d) | | `--from ` | start date (instead of --span) | | `--to ` | end date | | `--time-zone ` | UTC offset for diskspace, e.g. 02:00 (default: local time zone) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `GET /sites/environments/{env_id}/analytics/visits`, `GET /sites/environments/{env_id}/analytics/bandwidth`, `GET /sites/environments/{env_id}/analytics/cdn-bandwidth`, `GET /sites/environments/{env_id}/analytics/top-countries`, `GET /sites/environments/{env_id}/analytics/top-cities`, `GET /sites/environments/{env_id}/analytics/top-client-ips`, `GET /sites/environments/{env_id}/analytics/top-asns`, `GET /sites/environments/{env_id}/analytics/top-browsers`, `GET /sites/environments/{env_id}/analytics/top-hosts`, `GET /sites/environments/{env_id}/analytics/top-referrers`, `GET /sites/environments/{env_id}/analytics/top-uas`, `GET /sites/environments/{env_id}/analytics/visits-dispersion`, `GET /sites/environments/{env_id}/analytics/response-codes`, `GET /sites/environments/{env_id}/analytics/bot-protection/traffic-flow`, `GET /sites/environments/{env_id}/analytics/bot-protection/requests`, `GET /sites/environments/{env_id}/analytics/bot-protection/protection-results`, `GET /sites/environments/{env_id}/analytics/bot-protection/top-breakdown`, `GET /sites/environments/{env_id}/analytics/diskspace` The first argument is the metric, and is one of the choices in the reference above. They fall in a few groups: * Over time: `visits`, `bandwidth`, `cdn-bandwidth`, `diskspace`, `response-codes`. * Top lists: `top-countries`, `top-cities`, `top-ips`, `top-asns`, `top-browsers`, `top-hosts`, `top-referrers`, `top-user-agents`. * Distribution of visits: `visits-dispersion`. * Bot protection: `bot-traffic-flow`, `bot-requests`, `bot-protection-results`, `bot-top-breakdown`. ### Choosing the period [Section titled “Choosing the period”](#choosing-the-period) `--span` takes `24h`, `7d`, `30d` or `60d`, and defaults to `7d`. For a custom period use `--from` and `--to` instead; the values are passed to the API as given, for example `2026-10-01` and `2026-10-31`. `--span` cannot be combined with `--from` or `--to`; the command fails with a `USAGE` error before it sends a request. The `diskspace` metric has no `24h` span, so use `7d`, `30d` or `60d` there. ```sh kinstactl analytics visits my-site --env live --from 2026-10-01 --to 2026-10-31 ``` ### Disk space and time zones [Section titled “Disk space and time zones”](#disk-space-and-time-zones) `--time-zone` only applies to `diskspace`; with any other metric the command fails with a `USAGE` error. It takes a whole-hour UTC offset such as `02:00` or `-05:00`, and defaults to the offset of your local time zone, rounded toward zero to whole hours. ```sh kinstactl analytics diskspace my-site --env live --time-zone 02:00 ``` ### Output [Section titled “Output”](#output) Without `--json` the command prints tables on stdout: a heading line and a key/value table per series for the metrics over time, and a table per list for the others. With `--json` it prints the raw API response and nothing else, which is the way to get the exact numbers into a script: ```sh kinstactl analytics visits my-site --env live --span 24h --json ``` # auth > Log in with a Kinsta API key, check the active credentials and manage stored profiles. The `auth` commands manage the credentials kinstactl uses to talk to the Kinsta API. They are stored per profile; see [Authentication](/getting-started/authentication/) for the full story, including the environment variables for CI. ```sh kinstactl auth login kinstactl auth status kinstactl auth profiles ``` ## auth login [Section titled “auth login”](#auth-login) Validate an API key and store it, together with your company ID, in a profile. ```sh kinstactl auth login --profile work --api-key - < key.txt ``` ```sh kinstactl auth login [options] ``` Validate an API key and store it in a profile #### Options | Option | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `--api-key ` | API key (required when not interactive); "-" reads it from stdin. A literal key ends up in your shell history: prefer "--api-key -" or KINSTA_API_KEY | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /validate` The key is validated against Kinsta (`GET /validate`) before anything is stored, and the company ID is the one Kinsta reports for that key, so you never type it yourself. A key passed as a literal `--api-key ` ends up in your shell history. Pass `-` to read it from stdin instead. When stdin is not a terminal and no `--api-key` is given, the command fails with a `USAGE` error instead of prompting. Use the global `--profile ` to store the key under a named profile. ## auth status [Section titled “auth status”](#auth-status) Show the active credentials and validate them against Kinsta. ```sh kinstactl auth status ``` ```sh kinstactl auth status [options] ``` Show the active credentials and validate them against Kinsta Kinsta API: `GET /validate` The output names the source of the credentials (`env` for `KINSTA_API_KEY` and `KINSTA_COMPANY_ID`, `profile` for a stored profile), the profile, the company ID, the name and status of the key and when it expires. The key itself is never printed. Because the key is validated against Kinsta, the command fails when the key has been revoked, which makes it a quick check at the start of a CI job. ## auth logout [Section titled “auth logout”](#auth-logout) Remove a stored profile. ```sh kinstactl auth logout --profile work ``` ```sh kinstactl auth logout [options] ``` Remove a stored profile The profile is selected by the usual rules (`--profile`, `KINSTA_PROFILE`, the default profile), and the command fails with a `USAGE` error when that profile does not exist. Credentials that come from environment variables are not affected. ## auth profiles [Section titled “auth profiles”](#auth-profiles) List the stored profiles. ```sh kinstactl auth profiles ``` ```sh kinstactl auth profiles [options] ``` List stored profiles The table shows each profile with its company ID and key name, and marks the default profile. See [Profiles](/getting-started/profiles/) for working with more than one company. # backups > List, create, restore and delete backups, and create downloadable backup archives. The `backups` commands manage the backups Kinsta keeps of an environment, and the downloadable archives you can take off Kinsta. ```sh kinstactl backups list my-site --env live kinstactl backups create my-site --env live --tag "before plugin update" kinstactl backups restore my-site 123456789 --env live --notify rick@example.com ``` Backups belong to an environment. Without `--env`, the site’s only environment is used; see [Sites and environments](/getting-started/sites-and-environments/). Creating, restoring and deleting wait for Kinsta to finish by default, and accept `--no-wait`, `--timeout ` and `--dry-run`; see [operations](/commands/operations/). ## backups list [Section titled “backups list”](#backups-list) List the backups of an environment, newest first. ```sh kinstactl backups list my-site --env staging --type manual ``` ```sh kinstactl backups list [site] [options] ``` List the backups of an environment, newest first #### Arguments | Argument | Description | | -------- | --------------- | | `site` | site name or ID | #### Options | Option | Description | | --------------- | ------------------------------------------------------- | | `--env ` | environment (default: the only one) | | `--type ` | only this backup type, e.g. manual, scheduled or system | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites/environments/{env_id}/backups` The table shows the backup ID, its type, the note and when it was created. You need the ID for `backups restore` and `backups delete`. `--type` keeps only one kind of backup, for example `manual`, `scheduled` or `system`. ## backups create [Section titled “backups create”](#backups-create) Create a manual backup. ```sh kinstactl backups create my-site --env live --tag "before plugin update" ``` ```sh kinstactl backups create [site] [options] ``` Create a manual backup #### Arguments | Argument | Description | | -------- | --------------- | | `site` | site name or ID | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment (default: the only one) | | `--tag ` | label for the backup | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `POST /sites/environments/{env_id}/manual-backups` Take a manual backup before a risky change such as a plugin update or an [`env push`](/commands/env/#env-push). `--tag` labels the backup so you recognise it later. ## backups restore [Section titled “backups restore”](#backups-restore) Restore a backup, replacing the environment. ```sh kinstactl backups restore my-site 123456789 --notify rick@example.com ``` ```sh kinstactl backups restore [options] ``` Restore a backup, replacing the environment #### Arguments | Argument | Description | | ----------- | ---------------------------- | | `site` | site name or ID | | `backup-id` | backup ID, see: backups list | #### Options | Option | Description | | -------------------------- | ----------------------------------------------------- | | `--env ` | environment to restore to (default: the only one) | | `--from-env ` | environment the backup was taken on (default: --env) | | `--notify ` | company user to notify when the restore finishes | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | | `--yes` | skip the confirmation prompt | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Caution Asks for confirmation on a TTY. Pass `--yes` to skip it; without a TTY and without `--yes` the command fails. Kinsta API: `GET /sites/environments/{env_id}/backups`, `GET /company/{id}/users`, `POST /sites/environments/{target_env_id}/backups/restore` Restoring replaces the content of the environment with the backup, so the command asks for confirmation. On a terminal you answer a prompt; in a script pass `--notify ` and `--yes`. Without `--notify` a script fails with `USAGE` (there is no user to notify), and without `--yes` it fails with `CONFIRMATION_REQUIRED` (exit code 5). `--notify` takes the email of a company user, who is notified when the restore finishes. By default the backup is restored onto the environment it was taken on. With `--from-env` you restore a backup taken on another environment of the same site onto `--env`, for example a staging backup onto live: ```sh kinstactl backups restore my-site 123456789 --from-env staging --env live --notify rick@example.com ``` The backup ID is looked up in `--from-env`, and the confirmation names both environments, so you can see that the content of `live` is about to be replaced by a backup from `staging`. ## backups delete [Section titled “backups delete”](#backups-delete) Delete a backup. ```sh kinstactl backups delete my-site 123456789 --env staging --yes ``` ```sh kinstactl backups delete [options] ``` Delete a backup #### Arguments | Argument | Description | | ----------- | ---------------------------- | | `site` | site name or ID | | `backup-id` | backup ID, see: backups list | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment (default: the only one) | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | | `--yes` | skip the confirmation prompt | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Caution Asks for confirmation on a TTY. Pass `--yes` to skip it; without a TTY and without `--yes` the command fails. Kinsta API: `GET /sites/environments/{env_id}/backups`, `DELETE /sites/environments/backups/{backup_id}` The backup is looked up first, and the confirmation shows its ID and creation time. On a terminal you answer a prompt; in a script pass `--yes`. ## backups downloadable list [Section titled “backups downloadable list”](#backups-downloadable-list) List the downloadable backup archives of an environment. ```sh kinstactl backups downloadable list my-site --env live ``` ```sh kinstactl backups downloadable list [site] [options] ``` List the downloadable backup archives of an environment #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | #### Options | Option | Description | | --------------------- | ---------------------- | | `--env ` | environment name or ID | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `GET /sites/environments/{env_id}/downloadable-backups` A downloadable backup is an archive you can download from Kinsta, as opposed to the backups above, which you can only restore. The table shows when each archive was created and when it expires. ## backups downloadable create [Section titled “backups downloadable create”](#backups-downloadable-create) Create a downloadable backup archive. ```sh kinstactl backups downloadable create my-site --env live ``` ```sh kinstactl backups downloadable create [site] [options] ``` Create a downloadable backup archive #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment name or ID | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `POST /sites/environments/{env_id}/downloadable-backups`, `GET /sites/environments/{env_id}/downloadable-backups` When the archive is ready, the command prints its download link. With `--no-wait` it returns the operation ID instead, and you collect the link later with `backups downloadable list`. Kinsta limits how often you can create one; check that with `backups downloadable quota` first. ## backups downloadable quota [Section titled “backups downloadable quota”](#backups-downloadable-quota) Check whether a new downloadable backup can be created. ```sh kinstactl backups downloadable quota my-site --env live ``` ```sh kinstactl backups downloadable quota [site] [options] ``` Check whether a new downloadable backup can be created #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | #### Options | Option | Description | | --------------------- | ---------------------- | | `--env ` | environment name or ID | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `GET /sites/environments/{env_id}/next-downloadable-backup-available` The command prints `available` when you can create a new archive now, and otherwise when the next one becomes available. # cache > Clear the site, edge and CDN caches of an environment and switch edge caching and image optimization. Kinsta caches a site in three places: the site cache of the environment itself, the edge cache and the CDN. The `cache` commands clear each of them and control edge caching and CDN image optimization. ```sh kinstactl cache clear my-site --env live kinstactl cache edge clear my-site --env live kinstactl cache cdn clear my-site --env live ``` Clearing a cache is not destructive, so none of these commands asks for confirmation. They wait for Kinsta to finish by default, and accept `--no-wait`, `--timeout ` and `--dry-run`; see [operations](/commands/operations/). ## cache clear [Section titled “cache clear”](#cache-clear) Clear the site cache of an environment. ```sh kinstactl cache clear my-site --env live ``` ```sh kinstactl cache clear [site] [options] ``` Clear the site cache of an environment #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment name or ID | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `POST /sites/tools/clear-cache` Use this after a deploy or a content import, when a page still shows old content. It clears the site cache of that one environment, not the edge cache or the CDN. ## cache edge clear [Section titled “cache edge clear”](#cache-edge-clear) Clear the edge cache of an environment. ```sh kinstactl cache edge clear my-site --env live --url https://example.com/blog/ --subdirectories ``` ```sh kinstactl cache edge clear [site] [options] ``` Clear the edge cache of an environment #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment name or ID | | `--url ` | clear only this URL | | `--subdirectories` | also clear the subdirectories of --url | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `POST /sites/edge-caching/clear` Without `--url`, the whole edge cache of the environment is cleared. With `--url` only that URL is cleared, and `--subdirectories` extends that to everything below it. ## cache edge enable [Section titled “cache edge enable”](#cache-edge-enable) Enable edge caching of an environment. ```sh kinstactl cache edge enable my-site --env live ``` ```sh kinstactl cache edge enable [site] [options] ``` Enable edge caching of an environment #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment name or ID | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `PUT /sites/edge-caching/status` Edge caching is a setting per environment. Use this command and `cache edge disable` to switch it, for example to turn it off while you debug a caching problem and on again afterwards. ## cache edge disable [Section titled “cache edge disable”](#cache-edge-disable) Disable edge caching of an environment. ```sh kinstactl cache edge disable my-site --env live ``` ```sh kinstactl cache edge disable [site] [options] ``` Disable edge caching of an environment #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment name or ID | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `PUT /sites/edge-caching/status` The counterpart of `cache edge enable`. ## cache cdn clear [Section titled “cache cdn clear”](#cache-cdn-clear) Clear the CDN cache of an environment. ```sh kinstactl cache cdn clear my-site --env live ``` ```sh kinstactl cache cdn clear [site] [options] ``` Clear the CDN cache of an environment #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment name or ID | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites/{site_id}/environments`, `POST /sites/cdn/clear-cache` Use this when static files such as images, CSS or JavaScript are served stale from the CDN. ## cache cdn image-optimization [Section titled “cache cdn image-optimization”](#cache-cdn-image-optimization) Show or set the CDN image optimization of an environment. ```sh kinstactl cache cdn image-optimization my-site lossy --env live ``` ```sh kinstactl cache cdn image-optimization [type] [options] ``` Show or set the CDN image optimization of an environment #### Arguments | Argument | Description | | -------- | -------------------------------------------------------------------------------- | | `site` | site name, display name or ID | | `type` | set this type; omit to show the current one Choices: `off`, `lossy`, `lossless`. | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment name or ID | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `GET /sites/{site_id}/environments`, `PUT /sites/cdn/image-optimization` Without a `type`, the command shows the current setting. With `off`, `lossy` or `lossless` it changes the setting; only that form is an operation that waits and accepts `--dry-run`. To read the current value: ```sh kinstactl cache cdn image-optimization my-site --env live ``` # commands > List every command with its arguments, options and API endpoints, for people and for scripts. The `commands` command prints the full command tree of kinstactl. It needs no credentials and makes no request. ```sh kinstactl commands kinstactl commands --json ``` ## commands [Section titled “commands”](#commands) List all commands, their options and the API endpoints they use. ```sh kinstactl commands ``` ```sh kinstactl commands [options] ``` List all commands, their options and the API endpoints they use Without `--json` the command prints the tree as indented text: one line per command with its arguments (`` for a required one, `[site]` for an optional one) and its description. Options are not part of this view; for those use `--help` on a command, or `--json`. ### The JSON tree [Section titled “The JSON tree”](#the-json-tree) With `--json` the command prints the whole tree as one JSON document, starting at the `kinstactl` program itself. Every node has the same shape: | Field | Meaning | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | The last word of the command, such as `list`. | | `path` | The full command, such as `backups downloadable list`; empty for the root. | | `description` | The one-line description. | | `arguments` | The positional arguments, each with `name`, `required`, `description` and, when the values are fixed, `choices`. | | `options` | The flags, each with `flags` and `description`. | | `destructive` | `"confirm"` when the command asks for confirmation (`--yes` skips it), `"irreversible"` when you must pass `--confirm `, or `null`. | | `endpoints` | The Kinsta API endpoints the command calls, such as `GET /sites`. | | `commands` | The child nodes. A node without children is a command you can run. | The root node lists the options that apply to every command (`--profile`, `--json`, `--no-input`), and every command node repeats them in its own `options`. The tree is generated from the same definitions that drive the commands, so it is always current. A script can use it to find the commands that change something, or the endpoints a command depends on: ```sh kinstactl commands --json | jq '[.. | objects | select(.destructive != null) | .path]' ``` # company > Manage company users and their roles, and list API keys, regions, activity, plugins and themes of the company. The `company` commands work on the company your API key belongs to: its users and their roles, its API keys, the regions you can create sites in, its activity log, and the plugins and themes in use across all its sites. ```sh kinstactl company users list kinstactl company activity --category siteActions --limit 25 kinstactl company plugins --updates --vulnerable ``` All of them are scoped to the company of the active profile; see [profiles](/getting-started/profiles/). The listing commands only read. The two role commands change something and accept `--dry-run`, `--no-wait` and `--timeout `; see [operations](/commands/operations/). Neither asks for confirmation. ## company users list [Section titled “company users list”](#company-users-list) List the users of the company with their roles. ```sh kinstactl company users list ``` ```sh kinstactl company users list [options] ``` List the users of the company with their roles Kinsta API: `GET /company/{id}/users` The table shows each user’s email, name, roles and ID. Use the email, the full name or the ID wherever another command asks for a ``. ## company users get [Section titled “company users get”](#company-users-get) Show a company user and the roles they hold. ```sh kinstactl company users get jan@example.com ``` ```sh kinstactl company users get [options] ``` Show a company user and the roles they hold #### Arguments | Argument | Description | | -------- | ----------------------------------------------- | | `user` | email, full name or ID, see: company users list | Kinsta API: `GET /company/{id}/users`, `GET /company/{id}/users/{id_user}` The user is looked up by exact email, ID or full name first, then by a unique prefix. If several users match, the command fails with a `USAGE` error that lists their emails; it never picks one for you. The output shows the email, name and two-factor setting, followed by a table with the roles of the user and the company or site each role applies to. ## company users role [Section titled “company users role”](#company-users-role) Set the company-wide role of a user. ```sh kinstactl company users role jan@example.com company-developer ``` ```sh kinstactl company users role [options] ``` Set the company-wide role of a user #### Arguments | Argument | Description | | -------- | ------------------------------------------------------------------------------ | | `user` | email, full name or ID, see: company users list | | `role` | company role Choices: `company-admin`, `company-developer`, `company-billing`. | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /company/{id}/users`, `POST /company/{company_id}/users/company-capabilities` The role is one of `company-admin`, `company-developer` or `company-billing`. On success the command prints ` is now `; with `--json` you get `user_id`, `role`, `status` and, when Kinsta started an operation, its `operation_id`. ## company users site-role [Section titled “company users site-role”](#company-users-site-role) Set the role of a user on one site. ```sh kinstactl company users site-role jan@example.com my-site site-developer ``` ```sh kinstactl company users site-role [options] ``` Set the role of a user on one site #### Arguments | Argument | Description | | -------- | -------------------------------------------------- | | `user` | email, full name or ID, see: company users list | | `site` | site name, display name or ID | | `role` | site role Choices: `site-admin`, `site-developer`. | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /company/{id}/users`, `GET /sites`, `POST /company/{company_id}/users/site-capabilities` The role is `site-admin` or `site-developer`, and applies to the one site. The site is resolved against fresh data, not the cache. See [Sites and environments](/getting-started/sites-and-environments/) for how a site is named. ## company api-keys [Section titled “company api-keys”](#company-api-keys) List the API keys of the company. ```sh kinstactl company api-keys ``` ```sh kinstactl company api-keys [options] ``` List the API keys of the company Kinsta API: `GET /company/{id}/api-keys` The table shows the name, status, expiry (`never` when the key does not expire) and ID of each key. The key itself is never shown. ## company regions [Section titled “company regions”](#company-regions) List the regions a site can be created in. ```sh kinstactl company regions ``` ```sh kinstactl company regions [options] ``` List the regions a site can be created in Kinsta API: `GET /company/{id}/available-regions` The table shows the region ID and its name. The ID is what [`sites create`](/commands/sites/) takes in `--region`. ## company activity [Section titled “company activity”](#company-activity) Show the activity log of the company. ```sh kinstactl company activity --category siteActions --site my-site --limit 25 ``` ```sh kinstactl company activity [options] ``` Show the activity log of the company #### Options | Option | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------- | | `--limit ` | number of entries | | `--offset ` | entries to skip | | `--category ` | one of: siteActions, kinstaDns, migrations, billing, notifications, userManagement, personalSettings, samlSso | | `--site ` | only entries of this site (name, display name or ID) | | `--language ` | language of the descriptions: da, de, en, es, fr, it, ja, nl, pt, sv | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `GET /company/{id}/activity-logs` The command shows 10 entries by default; page through the log with `--limit` and `--offset`. The table shows the date, type, site ID, who started it (a user or an API key) and the status (`done`, `pending`, `warning` or `failed`). A line such as `10 of 340` goes to stderr. `--category` narrows the log to one of `siteActions`, `kinstaDns`, `migrations`, `billing`, `notifications`, `userManagement`, `personalSettings` or `samlSso`. `--site` keeps the entries of one site, by name, display name or ID. `--language` sets the language of the descriptions to one of `da`, `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pt` or `sv`. ## company plugins [Section titled “company plugins”](#company-plugins) List the plugins in use across the company. ```sh kinstactl company plugins --updates --vulnerable ``` ```sh kinstactl company plugins [options] ``` List the plugins in use across the company (filters apply client-side) #### Options | Option | Description | | -------------- | ----------------------------------------------- | | `--updates` | only plugins with an update available | | `--vulnerable` | only plugins whose latest version is vulnerable | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /company/{id}/wp-plugins` The table shows each plugin once, with its latest version, the number of environments that use it, the number of pending updates and whether the latest version is vulnerable. This is the company-wide inventory; for one environment use [`plugins list`](/commands/plugins/). `--updates` keeps plugins with at least one update available, and `--vulnerable` keeps plugins whose latest version is vulnerable. Both filters are applied by kinstactl after the full inventory is fetched, and combining them keeps only plugins that match both. When the inventory is empty, the command prints a message with the time it was last updated instead of a table. ## company themes [Section titled “company themes”](#company-themes) List the themes in use across the company. ```sh kinstactl company themes --updates ``` ```sh kinstactl company themes [options] ``` List the themes in use across the company (filters apply client-side) #### Options | Option | Description | | -------------- | ---------------------------------------------- | | `--updates` | only themes with an update available | | `--vulnerable` | only themes whose latest version is vulnerable | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /company/{id}/wp-themes` Works like `company plugins`, with the same table, the same `--updates` and `--vulnerable` filters and the same message for an empty inventory. For one environment use [`themes list`](/commands/themes/). # completion > Print the shell completion script for zsh, bash or fish. The `completion` commands print a completion script that makes your shell complete kinstactl commands, flags, site names and environment names. ```sh kinstactl completion zsh > "${fpath[1]}/_kinstactl" eval "$(kinstactl completion bash)" kinstactl completion fish > ~/.config/fish/completions/kinstactl.fish ``` Each command prints the script of one shell to stdout, so you install it by redirecting the output to the place your shell loads completions from, or by evaluating it. With `--json` the command prints an object with the `shell` and the `script`. Site and environment names come from the site cache; see [Sites and environments](/getting-started/sites-and-environments/). ## completion zsh [Section titled “completion zsh”](#completion-zsh) Print the zsh completion script. ```sh kinstactl completion zsh > "${fpath[1]}/_kinstactl" ``` ```sh kinstactl completion zsh [options] ``` Print the zsh completion script This writes the script to the first directory in your `fpath`, under the name `_kinstactl` that zsh looks for. Start a new shell to load it. ## completion bash [Section titled “completion bash”](#completion-bash) Print the bash completion script. ```sh eval "$(kinstactl completion bash)" ``` ```sh kinstactl completion bash [options] ``` Print the bash completion script Put the `eval` line in your `~/.bashrc` to load the script in every shell. ## completion fish [Section titled “completion fish”](#completion-fish) Print the fish completion script. ```sh kinstactl completion fish > ~/.config/fish/completions/kinstactl.fish ``` ```sh kinstactl completion fish [options] ``` Print the fish completion script Fish loads every file in `~/.config/fish/completions`, so the script is active in the next shell you start. ## completion sites [Section titled “completion sites”](#completion-sites) Print the site names for shell completion. ```sh kinstactl completion sites ``` ```sh kinstactl completion sites [options] ``` Print the site names for shell completion Kinsta API: `GET /sites` A helper that the completion scripts call to complete a `` argument; you do not run it yourself. It prints one site name per line from the site cache, and fetches the list from Kinsta only when the cache has expired. ## completion envs [Section titled “completion envs”](#completion-envs) Print the environment names of a site for shell completion. ```sh kinstactl completion envs my-site ``` ```sh kinstactl completion envs [site] [options] ``` Print the environment names of a site for shell completion #### Arguments | Argument | Description | | -------- | --------------- | | `site` | site name or ID | Kinsta API: `GET /sites` A helper that the completion scripts call to complete `--env`; you do not run it yourself. It prints one environment name of the site per line, from the site cache, and never opens the site picker. # db > Open the database of an environment in phpMyAdmin. The `db` command gives you access to the database of an environment through phpMyAdmin. For changing text in the database, see [search-replace](/commands/search-replace/). ```sh kinstactl db login my-site --env live ``` ## db login [Section titled “db login”](#db-login) Create a phpMyAdmin login link. ```sh kinstactl db login my-site --env live ``` ```sh kinstactl db login [site] [options] ``` Create a phpMyAdmin login link #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment name or ID | | `--dry-run` | print the resolved target and request; change nothing | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `POST /sites/environments/{env_id}/pma-login-token` The command prints a URL on stdout. Open it in a browser to be logged in to phpMyAdmin without a password. With `--json` it prints `url` and `expires_at`, so a script can see how long the link is valid. Treat the URL like a password while it is valid. Without `--env`, a site with one environment uses it; a site with several gets a picker on a terminal and fails with `ENV_REQUIRED` in a script. See [Sites and environments](/getting-started/sites-and-environments/). The command accepts `--dry-run`, but has no `--no-wait`. # dns > List the DNS zones of the company and manage the records in them. The `dns` commands manage the DNS zones Kinsta hosts for your company and the records inside them. They work on zones, not on sites, so they take no `--env`. ```sh kinstactl dns zones kinstactl dns records list example.com kinstactl dns records add example.com A www --value 203.0.113.10 ``` Wherever a command takes a ``, give the zone name or its ID; a unique prefix of the name also works, and an ambiguous one fails with the matching names. Records are identified by their `` and ``, for example `A` and `www`. Commands that change records wait for Kinsta to finish by default, and accept `--no-wait`, `--timeout ` and `--dry-run`; see [operations](/commands/operations/). ## dns zones [Section titled “dns zones”](#dns-zones) List the DNS zones of the company. ```sh kinstactl dns zones ``` ```sh kinstactl dns zones [options] ``` List the DNS zones of the company Kinsta API: `GET /domains` The table shows the name, ID and linked site of each zone, and whether it is active. Use it to find the zone name for the other commands. ## dns records list [Section titled “dns records list”](#dns-records-list) List the DNS records of a zone. ```sh kinstactl dns records list example.com ``` ```sh kinstactl dns records list [options] ``` List the DNS records of a zone #### Arguments | Argument | Description | | -------- | ------------------------------- | | `zone` | zone name or ID, see: dns zones | Kinsta API: `GET /domains`, `GET /domains/{domain_id}/dns-records` The table shows the type, name and TTL of each record, and its values. A record with several values, such as a round-robin `A` record, shows them comma-separated. ## dns records add [Section titled “dns records add”](#dns-records-add) Add a DNS record to a zone. ```sh kinstactl dns records add example.com A www --value 203.0.113.10 ``` ```sh kinstactl dns records add [options] ``` Add a DNS record to a zone #### Arguments | Argument | Description | | -------- | ---------------------------------- | | `zone` | zone name or ID, see: dns zones | | `type` | record type, e.g. A | | `name` | record name, e.g. www\.example.com | #### Options | Option | Description | | --------------------- | -------------------------------------------------------- | | `--value ` | record value; repeat the values for a round-robin record | | `--ttl ` | time to live in seconds, at least 300 | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /domains`, `POST /domains/{domain_id}/dns-records` `--value` is required; without it the command fails with a `USAGE` error, there is no prompt. Repeat the values after one `--value` to create a round-robin record, and set the TTL with `--ttl`: ```sh kinstactl dns records add example.com A @ --value 203.0.113.10 203.0.113.11 --ttl 600 ``` `--ttl` is in seconds, at least 300, which is also the default. ## dns records update [Section titled “dns records update”](#dns-records-update) Change the TTL or values of a DNS record. ```sh kinstactl dns records update example.com A www --ttl 600 ``` ```sh kinstactl dns records update [options] ``` Change the TTL or values of a DNS record #### Arguments | Argument | Description | | -------- | ---------------------------------- | | `zone` | zone name or ID, see: dns zones | | `type` | record type, e.g. A | | `name` | record name, e.g. www\.example.com | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--ttl ` | new time to live in seconds, at least 300 | | `--add ` | values to add to the record | | `--remove ` | values to remove from the record | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /domains`, `PUT /domains/{domain_id}/dns-records` Pass at least one of `--ttl`, `--add` and `--remove`; with none the command fails with `Nothing to change`. `--add` and `--remove` change the values of the record, each taking one or more values: ```sh kinstactl dns records update example.com A www --add 203.0.113.11 --remove 203.0.113.10 ``` ## dns records delete [Section titled “dns records delete”](#dns-records-delete) Delete a DNS record from a zone. ```sh kinstactl dns records delete example.com A www --yes ``` ```sh kinstactl dns records delete [options] ``` Delete a DNS record from a zone #### Arguments | Argument | Description | | -------- | ---------------------------------- | | `zone` | zone name or ID, see: dns zones | | `type` | record type, e.g. A | | `name` | record name, e.g. www\.example.com | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | | `--yes` | skip the confirmation prompt | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Caution Asks for confirmation on a TTY. Pass `--yes` to skip it; without a TTY and without `--yes` the command fails. Kinsta API: `GET /domains`, `DELETE /domains/{domain_id}/dns-records` Deleting removes the record with all its values, so the command asks for confirmation. On a terminal you answer a prompt; in a script pass `--yes`, otherwise it fails with `CONFIRMATION_REQUIRED` (exit code 5). # domains > List, add and remove the domains of an environment, change the primary domain and look up its DNS records. The `domains` commands manage the domains that point at an environment. To manage the DNS records of a zone hosted at Kinsta, see [dns](/commands/dns/). ```sh kinstactl domains list my-site --env live kinstactl domains add my-site example.com --env live kinstactl domains primary my-site example.com --env live ``` Domains belong to an environment. Without `--env`, a site with one environment uses it; a site with several gets a picker on a terminal and fails with `ENV_REQUIRED` in a script. See [Sites and environments](/getting-started/sites-and-environments/). `domains add`, `domains remove` and `domains primary` wait for Kinsta to finish by default, and accept `--no-wait`, `--timeout ` and `--dry-run`; see [operations](/commands/operations/). Where a command takes a ``, you can give the domain name or its ID; a unique prefix of the name also works. ## domains list [Section titled “domains list”](#domains-list) List the domains of an environment. ```sh kinstactl domains list my-site --env staging ``` ```sh kinstactl domains list [site] [options] ``` List the domains of an environment #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | #### Options | Option | Description | | --------------------- | ---------------------- | | `--env ` | environment name or ID | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `GET /sites/environments/{env_id}/domains` The table shows the name and ID of each domain, and whether it uses Cloudflare DNS. ## domains add [Section titled “domains add”](#domains-add) Add a domain to an environment. ```sh kinstactl domains add my-site example.com --env live ``` ```sh kinstactl domains add [options] ``` Add a domain to an environment #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | | `domain` | domain name to add | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment name or ID | | `--with-www` | also add the www subdomain (requires --wildcard) | | `--wildcard` | also cover subdomains (clears is_wildcardless) | | `--setup-type ` | quick or avoid_downtime | | `--ssl-key ` | private key file of a custom SSL certificate | | `--ssl-cert ` | certificate file of a custom SSL certificate | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `POST /sites/environments/{env_id}/domains` By default the domain is added without wildcard support. Two flags widen that: * `--wildcard` also covers subdomains. * `--with-www` also adds the `www` subdomain. It requires `--wildcard`; without it the command fails with a `USAGE` error before anything is sent. `--setup-type` takes `quick` or `avoid_downtime`. To use your own certificate instead of the one Kinsta issues, pass the certificate and its private key as files: ```sh kinstactl domains add my-site example.com --env live --wildcard --with-www --ssl-cert cert.pem --ssl-key key.pem ``` `--ssl-cert` and `--ssl-key` must be given together, and both files must be readable and not empty. The key is sent to Kinsta and never echoed back: `--dry-run` shows the request with the key masked as `***`. ## domains remove [Section titled “domains remove”](#domains-remove) Remove a domain from an environment. ```sh kinstactl domains remove my-site example.com --env live --yes ``` ```sh kinstactl domains remove [options] ``` Remove a domain from an environment #### Arguments | Argument | Description | | -------- | ------------------------------------ | | `site` | site name, display name or ID | | `domain` | domain name or ID, see: domains list | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment name or ID | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | | `--yes` | skip the confirmation prompt | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Caution Asks for confirmation on a TTY. Pass `--yes` to skip it; without a TTY and without `--yes` the command fails. Kinsta API: `GET /sites`, `GET /sites/environments/{env_id}/domains`, `DELETE /sites/environments/{env_id}/domains` The domain is looked up first, so a typo fails with the list of domains the environment has. Removing is destructive, so the command asks for confirmation. On a terminal you answer a prompt; in a script pass `--yes`, otherwise it fails with `CONFIRMATION_REQUIRED` (exit code 5). ## domains primary [Section titled “domains primary”](#domains-primary) Change the primary domain of an environment. ```sh kinstactl domains primary my-site example.com --env live ``` ```sh kinstactl domains primary [options] ``` Change the primary domain of an environment #### Arguments | Argument | Description | | -------- | ------------------------------------ | | `site` | site name, display name or ID | | `domain` | domain name or ID, see: domains list | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--env ` | environment name or ID | | `--search-replace` | also rewrite the old URL in the database | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | | `--yes` | skip the confirmation prompt | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Caution Asks for confirmation on a TTY. Pass `--yes` to skip it; without a TTY and without `--yes` the command fails. Kinsta API: `GET /sites`, `GET /sites/environments/{env_id}/domains`, `PUT /sites/environments/{env_id}/change-primary-domain` The primary domain is the one the site is served on. Changing it alone needs no confirmation. With `--search-replace`, Kinsta also rewrites the old URL in the database to the new one. That changes content, so the command then asks for confirmation. On a terminal you answer a prompt; in a script pass `--yes`. ```sh kinstactl domains primary my-site example.com --env live --search-replace --yes ``` ## domains verification [Section titled “domains verification”](#domains-verification) Show the DNS records that verify and point a domain. ```sh kinstactl domains verification my-site example.com --env live ``` ```sh kinstactl domains verification [options] ``` Show the DNS records that verify and point a domain #### Arguments | Argument | Description | | -------- | ------------------------------------ | | `site` | site name, display name or ID | | `domain` | domain name or ID, see: domains list | #### Options | Option | Description | | --------------------- | ---------------------- | | `--env ` | environment name or ID | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Kinsta API: `GET /sites`, `GET /sites/environments/{env_id}/domains`, `GET /sites/environments/domains/{site_domain_id}/verification-records` The output has two tables, each with a type, name and value. Add the verification records to the domain’s DNS so Kinsta can confirm you own it, and the pointing records so the domain resolves to the environment. If the zone is hosted at Kinsta you can create them with [`dns records add`](/commands/dns/#dns-records-add). With `--json` you get the response as Kinsta returns it. # env > List, create, clone, push and delete the environments of a site. A site has a live environment and optionally one or more staging environments. The `env` commands manage those environments and move content between them. For actions on the whole site, see [sites](/commands/sites/). ```sh kinstactl env list my-site kinstactl env clone my-site dev --from live kinstactl env push my-site --from staging --to live ``` Commands that change an environment wait for Kinsta to finish by default, and accept `--no-wait`, `--timeout ` and `--dry-run`; see [operations](/commands/operations/). `--dry-run` prints the resolved target and the request that would be sent, and changes nothing. ## env list [Section titled “env list”](#env-list) List the environments of a site. ```sh kinstactl env list my-site ``` ```sh kinstactl env list [site] [options] ``` List the environments of a site #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | Kinsta API: `GET /sites`, `GET /sites/{site_id}/environments` Use it to find the names you pass to `--env` on other commands. ## env push [Section titled “env push”](#env-push) Push the database and/or files of one environment to another. ```sh kinstactl env push my-site --from staging --to live ``` ```sh kinstactl env push [site] [options] ``` Push the database and/or files of one environment to another #### Arguments | Argument | Description | | -------- | ----------------------------- | | `site` | site name, display name or ID | #### Options | Option | Description | | --------------------- | ----------------------------------------------------- | | `--from ` | source environment | | `--to ` | target environment (gets overwritten) | | `--no-db` | do not push the database | | `--no-files` | do not push files | | `--no-search-replace` | do not run search and replace on the database | | `--path ` | push only these paths instead of all files | | `--dry-run` | print the resolved target and request; change nothing | | `--no-wait` | return the operation ID instead of waiting | | `--timeout ` | give up waiting after this many minutes (default 30) | | `--yes` | skip the confirmation prompt | Global options `--profile`, `--json` and `--no-input` apply too. See [scripting and CI](/scripting-and-ci/). Caution Asks for confirmation on a TTY. Pass `--yes` to skip it; without a TTY and without `--yes` the command fails. Kinsta API: `GET /sites`, `PUT /sites/{site_id}/environments` `--to` is overwritten with the content of `--from`, so the command asks for confirmation first. On a terminal you answer a prompt. In a script, pass `--yes`, otherwise it fails with `CONFIRMATION_REQUIRED` (exit code 5). Without `--from` or `--to`, a terminal asks which environment you mean; in a script both are required, and they must be different environments. By default the database and all files are pushed, and a search and replace is run on the database. Narrow that down with the `--no-` options: ```sh kinstactl env push my-site --from staging --to live --no-db --path wp-content/themes --yes ``` * `--no-db` and `--no-files` skip one half of the push. Pushing neither is a `USAGE` error. * `--no-search-replace` skips that search and replace. * `--path` pushes only the given files or folders instead of all files, and cannot be combined with `--no-files`. ## env create [Section titled “env create”](#env-create) Create a new environment for a site. ```sh kinstactl env create my-site dev --admin-user admin --admin-email admin@example.com --admin-password - ``` ```sh kinstactl env create [options] ``` Create a new environment for a site #### Arguments | Argument | Description | | -------------- | ----------------------------------- | | `site` | site name, display name or ID | | `display-name` | display name of the new environment | #### Options | Option | Description | | ----------------------------- | -------------------------------------------------------- | | `--plain` | create an empty environment without WordPress | | `--premium` | create a premium staging environment | | `--admin-user ` | WordPress admin user name | | `--admin-email ` | WordPress admin email | | `--admin-password ` | "-" reads it from stdin; omitted on a TTY prompts for it | | `--title