{"id":15490998,"url":"https://github.com/chriswiegman/kana","last_synced_at":"2025-12-15T01:50:15.258Z","repository":{"id":59553883,"uuid":"480486568","full_name":"ChrisWiegman/kana","owner":"ChrisWiegman","description":"A simple, portable CLI for efficient WordPress development","archived":false,"fork":false,"pushed_at":"2025-10-03T19:23:22.000Z","size":3973,"stargazers_count":59,"open_issues_count":14,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-03T21:29:16.495Z","etag":null,"topics":["developer-tools","development-environment","docker","plugins","themes","wordpress"],"latest_commit_sha":null,"homepage":"https://github.com/ChrisWiegman/kana","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChrisWiegman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"ChrisWiegman","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2022-04-11T17:39:35.000Z","updated_at":"2025-10-03T19:23:25.000Z","dependencies_parsed_at":"2023-10-16T21:50:29.400Z","dependency_job_id":"7594d421-2c3c-4e9b-a86a-f48906dfb732","html_url":"https://github.com/ChrisWiegman/kana","commit_stats":null,"previous_names":["chriswiegman/kana","chriswiegman/kana-cli","chriswiegman/kana-dev"],"tags_count":70,"template":false,"template_full_name":null,"purl":"pkg:github/ChrisWiegman/kana","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisWiegman%2Fkana","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisWiegman%2Fkana/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisWiegman%2Fkana/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisWiegman%2Fkana/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChrisWiegman","download_url":"https://codeload.github.com/ChrisWiegman/kana/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisWiegman%2Fkana/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278712717,"owners_count":26032742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","development-environment","docker","plugins","themes","wordpress"],"created_at":"2024-10-02T07:42:15.206Z","updated_at":"2025-10-08T19:33:12.593Z","avatar_url":"https://github.com/ChrisWiegman.png","language":"Go","funding_links":["https://github.com/sponsors/ChrisWiegman"],"categories":[],"sub_categories":[],"readme":"# Kana\n\nKana is a CLI (command line) tool for developing WordPress sites, plugins and themes efficiently.\n\n# Why Kana?\n\nI've gone through many different tools to run WordPress locally over the years. All of them are either extremely complex or don't support basic features such as ensuring plugin and theme development can be a first-class experience. I rarely build sites with WordPress and I wanted a tool that will allow me to build the plugins and themes I do work on as efficiently as possible.\n\n# System requirements\n\n## MacOS\n\n- [Docker Desktop](https://www.docker.com)\n\n## Linux\n\n- [Docker Engine](https://docs.docker.com/engine/install/)\n\nDocker Desktop for Linux may work but I have not tested it.\n\n# Installing Kana\n\nThere are a few options for installing Kana. You can use [Homebrew](https://brew.sh) (recommended), you can install it from [the \"releases\" page](https://github.com/ChrisWiegman/kana/releases) here or you can build it manually.\n\n## Install from Homebrew\n\nInstalling from [Homebrew](https://brew.sh) is the recommended approach on both Mac and Linux as it allows for automatic updates when needed. To install from Homebrew run the following command:\n\n```\nbrew install ChrisWiegman/kana/kana\n```\n\nNote that, as there are numerous ways to install Docker, I have chosen, at least for now, to not list it as a dependency when installing via Homebrew. You'll want to make sure Docker is already installed or install it with `brew install --cask docker` if you're on Mac (see [this documentation](https://docs.docker.com/engine/install/) if you're in Linux).\n\n## Download from GitHub releases\n\nSimply download the latest release from our [release page](https://github.com/ChrisWiegman/kana/releases) and extract the CLI to a location accessible by your system PATH\n\n**Note for Mac users** I have not signed the download copy so you'll need to manually allow it in your Mac settings if you download it from the releases page. Install it via Homebrew to avoid this step.\n\n## Build manually\n\nYou will need [Go](https://go.dev) installed locally to build the application.\n\n1. Clone this repo `git clone https://github.com/ChrisWiegman/kana.git`\n2. CD into the repo and run `make install`\n\nAssuming you have Go properly setup with `GOBIN` in your system path, you should now be able to use Kana. Run `kana version` to test.\n\n# Updating Kana\n\nIf you build Kana from source you'll need to manually update Kana with a `git pull` and then a fresh build.\n\nIf you use Homebrew or install Kana from the releases page Kana will automatically check for updates and warn you of a new version. You can then update via homebrew, if that's how you installed it, or by running `kana update` which will replace the existing binary with the updated version.\n\n# Using Kana\n\nAt it's most basic you can start a zero-config Kana site by running `kana start` in your terminal. This will create a new Kana site based on your current directory and open it in your default browser.\n\nKana relies on [Traefik](https://traefik.io) to map real domains to local sites. You can run as many sites as you need and each will be mapped to a subdomain of _sites.kana.sh_.\n\n## Start\n\n`kana start` will start a kana site based on your current directory and open it in your browser. It will detect if the current directory is a plugin or a theme and start the site as the appropriate type.\n\nTo login to the new site use the following:\n\n- _User Name_: **admin**\n- _Password_: **password**\n\nNote: these can be changed in the config. Please see below.\n\n### Start options\n\n`--type` Defaults to `site` for developing a WordPress site. Can set to `plugin` map the current directory as a plugin within the created site or `theme` to map the current directory as a theme within the created site.\n\n`--xdebug` will start Xdebug on the site (see below for usage).\n\n`--wpdebug` will enable `WP_DEBUG` on the site.\n\n`--scriptdebug` will enable `SCRIPT_DEBUG` on the site.\n\n`--environment` allows the user to change the `WP_ENVIRONMENT_TYPE` constant. Defaults to `local`. Valid options are `local`, `devlopment`, `staging` and `production`.\n\n`--mailpit` will start an instance of [Mailpit](https://github.com/axllent/mailpit) to allow for email capture and troubleshooting.\n\n`--ssl` will set the site's default URLs to use SSL.\n\n`--name` The name flag allows you to run an arbitrary site from anywhere. For example, if you already started and stopped a site from a directory called _test_ you can run `kana start --name=test` to start that site from anywhere. If you use the `name` flag on a new site it will create that site without a link to any local folder. This can be handy for testing a plugin or other configuration but not that none of the other start flags will apply.\n\n`--multisite` Use the multisite flag to setup a WordPress Multisite installation. The optional `subdomain` and `subdirectory` flags will allow for either type of installation.\n\n`--removedefaultplugins` Will remove the default \"Hello Dolly\" and Akismet plugins when starting the site. Note this will not restore them if they've been manually removed.\n\n`--theme` Sets the default theme if you do not wish to use the theme bundled with WordPress. Will attempt to download the theme from wordpress.org. Does not work if the site type is set to \"theme\"\n\n`--plugins` A comma-separated list of plugins to install when starting the site.\n\n`--database` By default Kana uses [MariaDB](https://mariadb.org) for its WordPress database. You can use MySQL or [SQLite](https://www.sqlite.org/index.html) instead by specifying `mysql` or `sqlite` as the database type here.\n\n## Trusting the SSL certificate on Mac\n\nOn MacOS, Kana will automatically attempt to add its SSL certificate to the MacOS system Keychain the first time you start a site where SSL is the default. You can manually do this without starting a new site using the `kana trust-ssl` command.\n\n## Importing an existing WordPress database\n\nKana offers a simple way to import an existing WordPress database. Just use the `kana db import \u003cyour database file\u003e` to get started.\n\nIf you're coming from a site with a different home address you can specify `--replace-domain=\u003cmy old site domain\u003e` to automatically replace it with the appropriate domain for your dev site.\n\n### Example:\n\n`kana db import --replace-domain=chriswiegman.com database.sql` would import the file _database.sql_ from my current directory and rename the old site address, chriswiegman.com, to the current and correct site address to work in Kana.\n\n### Import options\n\n`--replace-domain` The domain of your source site to replace with the appropriate Kana domain\n`--preserve` Prevents Kana from dropping any existing database and overwrites what you have. Warning: this may result in unpredictable issues.\n\n### Exporting your Kana database\n\nYou can also export the database file your Kana site is using with `kana db export`. By default it will save the file in your default site directory but you can specify a relative path to the file where you would like to export your database if you wish.\n\n\u003e *Note* Currently importang and exporting databases only works with MariaDB databases. [I am working on bringing this functionality to MySQL](https://github.com/docker-library/wordpress/pull/902) and hope to have it available with MySQL soon. I do not anticipate bringing this to SQLite for a while.\n\n## Stop\n\n`kana stop` will stop the current site and, if no other sites are running, will shut down shared containers like Traefik as well.\n\n## List\n\n`kana list` will list all sites known by Kana and their current running status. Any site listed can then be addressed with the `name` flag in other commands.\n\n## Destroy\n\n`kana destroy` will stop and destroy the current site. This is different than `stop` in that `stop` will leave the database and files it creates alone so you can start it again later. Once destroyed a site is irrecoverable.\n\nBy default Kana will prompt you to confirm any site you wish to destroy. You can bypass the prompt by adding the `--force` flag to the destroy command.\n\n## Open\n\n`kana open` will open the site in your default browser\n\n`kana open -a` will open the WordPress Dashboard. This will also login the \"admin\" user unless the `automaticLogin` setting is set to false.\n\n`kana open -t` will open the Traefik dashboard.\n\nBy default Kana will open the appropriate WordPress site. To open the database or Mailpit simply append the appropriate flag to the open command ie `kana open --database`.\n\nNote that by default Kana will open the database in [phpMyAdmin](https://www.phpmyadmin.net). You can also tell Kana to open the database in [TablePlus](https://tableplus.com) instead by setting the `databaseClient` configuration setting to `tableplus`.\n\nCurrently pphpMyAdmin and TablePlus are the only two clients I've configured. If you would like to use a different client, please [open an issue](https://github.com/ChrisWiegman/kana/issues) and I'd be happy to take a look.\n\n\u003e *Note* Opening the Database directly with Kana doesn't work for SQLite databases. To open a SQLite database directly navigate to `\u003cyour-site-folder\u003e/wp-content/database/.ht.sqlite` and open the file directly.\n\n## wp-cli\n\n`kana wp \u003cWP-CLI COMMAND\u003e` will execute a [wp-cli](https://wp-cli.org) command on your site. For example `kana wp plugin list` will list all the plugins on the site and their associated statuses\n\n# Configuring Kana\n\nThe above commands will get an individual site up and running but there are a few more options to consider that can be changed for a given site or globally\n\n## Global Config\n\nKana has a handful of options that apply to all new sites created with the app. You can adjust these with the `config` command as noted below:\n\n`kana config` will list all changeable defaults for a new site. Currently these include the following:\n\n- `activate` **true** - if the project site is set to `theme` or `plugin` this will activate the project on first load\n- `adminEmail` __admin@kanasite.localhost__ - the admin email address for the default admin account\n- `adminPassword` **password** - the default password used to login to WordPress\n- `adminUser` **admin** - the default username used to login to WordPress\n- `automaticLogin` **true** - will automatically login the \"admin\" user when accessing the WordPress dashboard\n- `database` **mariadb** - Specify the database server for WordPress, currently either `mariadb`, `mysql` or `sqlite`\n- `databaseClient` **phpmyadmin** - the default database client for accessing the database directly (currently `phpmyadmin` and `tableplus` are supported)\n- `databaseVersion` **11** - the default database version used for sites. 11 is chosen for the default MariaDB database. You will need to update this if you switch to MySQL.\n- `environment` **local** - the default usage of the `environment` start flag\n- `mailpit` **false** - the default usage of the `mailpit` start flag\n- `multisite` **none** - set to either `subdirectory` or `subdomain` to create the site as the appropriate type of Multisite installation.\n- `php` **8.2** - the default PHP version used for new sites (see [https://hub.docker.com/_/wordpress] for all supported versions)\n- `removeDefaultPlugins` **false** - removes the default \"Hello Dolly\" and Akismet plugins when starting a new site. Note this will not restore them if they've already been removed.\n- `scriptDebug` **false** - the default usage of the `scriptDebug` wp-config item\n- `ssl` **false** - the default usage of the `ssl` start flag\n- `theme` ***\u003cempty string\u003e*** - the default theme to be installed from wordpress.org and activated with new sites\n- `type` **site** - the type of the Kana site you're starting. Current options are \"site\" \"plugin\" and \"theme\"\n- `updateInterval` **1** - the number of days Kana will wait between checking for updated Docker images and other updates. Set this to `0` to disable the check for newer images altogether (Kana will only download missing images)\n- `wpdebug` **false** - the default usage of the `wpdebug` start flag\n- `xdebug` **false** - the default usage of the `xdebug` start flag\n\nYou can get or set any of the above options using a similar syntax to GIT's config. For example:\n\n`kana config adminEmail` will print the value of the admin.email setting\n`kana config adminEmail myemail@somedomain.com` will change the value of the admin.email setting to \"myemail@somedomain.com\".\n\nThe above syntax will allow you to change the defaults for any of the options listed\n\n## Site Config\n\nIn addition to the global config, certain items above can be overridden for any given site. For a site without a `name` flag (as seen in the start command), simply create a _.kana.json_ file in the current directory. You can populate it with the following options:\n\n- `activate` **true** - if the project site is set to `theme` or `plugin` this will activate the project on first load\n- `adminEmail` __admin@kanasite.localhost__ - the admin email address for the default admin account\n- `adminPassword` **password** - the default password used to login to WordPress\n- `adminUser` **admin** - the default username used to login to WordPress\n- `automaticLogin` **true** - will automatically login the \"admin\" user when accessing the WordPress dashboard\n- `database` **mariadb** - Specify the database server for WordPress, currently either `mariadb`, `mysql` or `sqlite`\n- `databaseClient` **phpmyadmin** - the default database client for accessing the database directly (currently `phpmyadmin` and `tableplus` are supported)\n- `databaseVersion` **11** - the default database version used for sites. 11 is chosen for the default MariaDB database. You will need to update this if you switch to MySQL.\n- `environment` **local** - the default usage of the `environment` start flag\n- `mailpit` **false** - the default usage of the `mailpit` start flag\n- `multisite` **none** - set to either `subdirectory` or `subdomain` to create the site as the appropriate type of Multisite installation.\n- `php` **8.2** - the default PHP version used for new sites (see [https://hub.docker.com/_/wordpress] for all supported versions)\n- `plugins` **[]** - an array of plugins to install and activate when starting the new site. These are slugs from the Plugins section of WordPress.org.\n- `removeDefaultPlugins` **false** - removes the default \"Hello Dolly\" and Akismet plugins when starting a new site. Note this will not restore them if they've already been removed.\n- `scriptDebug` **false** - the default usage of the `scriptDebug` start flag\n- `ssl` **false** - the default usage of the `ssl` start flag\n- `theme` ***\u003cempty string\u003e*** - the default theme to be installed from wordpress.org and activated with the site\n- `type` **site** - the type of the Kana site you're starting. Current options are \"site\" \"plugin\" and \"theme\"\n- `wpdebug` **false** - the default usage of the `wpdebug` start flag\n- `xdebug` **false** - the default usage of the `xdebug` start flag\n\n### Export a sites Kana config automatically\n\n`kana export` will create a _.kana.json_ configuration file in your current folder exporting the configuration of the current site including PHP version, active plugins and associated options as shown above\n\n# Accessing the database directly\n\nCurrently there are two methods to access the database directly. First you can access the database via phpMyAdmin or TablePlus by running `kana open --database` for the site in question.\n\nNote that by default Kana will open the database in [phpMyAdmin](https://www.phpmyadmin.net). You can also tell Kana to open the database in [TablePlus](https://tableplus.com) instead by setting the `databaseClient` configuration setting to `tableplus`.\n\nYou can also access the database directly by viewing the database port with `docker ps` and using the database port and the following configuration in the app of your choice:\n\n- **Database host**: _kana\\_`your site name`\\_database_\n- **Database name**: _wordpress_\n- **Database user**: _wordpress_\n- **Database password**: _wordpress_\n\n# Verify you're using Kana\n\nYou can verify you're in a Kana environment by verifying the `IS_KANA_ENVIRONMENT` env variable. Here's an example:\n\n```php\nif ( getenv( 'IS_KANA_ENVIRONMENT' ) === true ) {\n    // We're on a Kana environment\n}\n```\n\n# Using Xdebug\n\nYou can setup [Xdebug](https://xdebug.org) when starting a site in Kana using the `--xdebug` flag with the start command or by setting the `xdebug` setting globally or at the site level.\n\nOnce a site is running you can see if Xdebug is running by using the `kana xdebug` command which will return _on_ if Xdebug is running or _off_ if it is not.\n\nTo start or stop Xdebug on a running site use `xdebug on` or `xdebug off` as appropriate. The output of this command will be either _on_ or _off_ to indicate the status of Xdebug when the command is complete.\n\nCurrently Kana only supports step debugging in xdebug. To use this with VSCode create a _.vscode/launch.json_ file with the following:\n\n```{\n    \"version\": \"0.2.0\",\n    \"configurations\": [\n        {\n            \"name\": \"Listen for XDebug\",\n            \"type\": \"php\",\n            \"request\": \"launch\",\n            \"port\": 9003,\n            \"log\": true,\n            \"pathMappings\": {\n                \"/var/www/html/wp-content/plugins/\u003cMY KANA FOLDER NAME\u003e/\": \"${workspaceFolder}\",\n                \"/var/www/html/\": \"${workspaceFolder}/wordpress\",\n            }\n        }\n    ]\n}\n```\n\nTo trigger step debugging you'll also need the appropriate extension for your browser:\n\n- [Xdebug Helper for Firefox](https://addons.mozilla.org/en-GB/firefox/addon/xdebug-helper-for-firefox/) ([source](https://github.com/BrianGilbert/xdebug-helper-for-firefox)).\n- [Xdebug Helper for Chrome](https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc) ([source](https://github.com/mac-cain13/xdebug-helper-for-chrome)).\n- [XDebugToggle for Safari](https://apps.apple.com/app/safari-xdebug-toggle/id1437227804?mt=12) ([source](https://github.com/kampfq/SafariXDebugToggle)).\n\n# Flushing cache and transients\n\nTwo wp-cli commands I find myself using regularly when working on WordPress are `wp transient delete --all` and `wp cache flush`. I use them so often that it seemed like a good idea to make them easier to access with Kana. As a result I've added the `kana flush` command which will call both on the specified site.\n\n# Viewing the Kana changelog\n\nIt's always good to know what's changed before updating. You can use `kana changelog` to take to Kana's releases on GitHub where you can view the current changes and look for anything you might want to wait on.\n\n# This project is under active development\n\nNote that I am using this project for my own work and it is under active development. Some of the things I'm currently working on include:\n\n- Better site management commands\n- Much more clear prompts and messages on the commands themselves\n- Writing a lot more tests (it's a personal project, I start where I can)\n- A proper website for all this documentation (I already bought a domain, after all)\n- Bugfixes and other tweaks as I find them necessary for my own use\n- Better integration with tools like VSCode and others\n\n# Completely Uninstalling Kana\n\nI hate apps that leave leftovers on your machine. When stopping a site all Docker resources except the images will be removed. To remove the app completely beyond that you'll want to delete the following:\n\n1. Delete the application from your $GOBIN or system path (or run `brew uninstall kana` if installed via homebrew)\n2. Delete the `~/.config/kana` folder which contains all site and app configuration\n3. (Mac only) Delete the `Kana Development CA` certificate from the _System_ keychain in the _Keychain Access_ app\n4. If installed via homebrew run `brew untap ChrisWiegman/kana` to remove the Homebrew tap\n\nYou can also safely remove any new images added however it is not a requirement. Many other apps might share those images leading to your system simply needing to download them again.\n\n# Using Kana in other projects\n\nWhile Kana cannot easily be used as a package itself, you can import the binary itself into your project. If you do so, consider using the `output-json` flag on all commands. This will convert all output to JSON format to make consumption easier when the Kana application is embedded elsewhere.\n\nWhy do this? This will make it easier for me to work with Kana in a small toolbar app I'm building as well as with a [Visual Studio Code](https://code.visualstudio.com/) extension I have planned which will allow me to see what is going on with Kana and control it beyond the terminal.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchriswiegman%2Fkana","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchriswiegman%2Fkana","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchriswiegman%2Fkana/lists"}