PHPackages                             arnoson/kirby-deploy - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [DevOps & Deployment](/categories/devops)
4. /
5. arnoson/kirby-deploy

ActiveKirby-plugin[DevOps & Deployment](/categories/devops)

arnoson/kirby-deploy
====================

0.4.1(3mo ago)1069[2 issues](https://github.com/arnoson/kirby-deploy/issues)MITTypeScriptCI passing

Since Mar 22Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/arnoson/kirby-deploy)[ Packagist](https://packagist.org/packages/arnoson/kirby-deploy)[ RSS](/packages/arnoson-kirby-deploy/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (2)Versions (12)Used By (0)

   ![](./.github/logo-light.svg)

Kirby Deploy
============

[](#kirby-deploy)

We have all been there: manually dragging and dropping files into an ftp client like FileZilla to upload our websites to the server. This is not only cumbersome, but also error-prone if you forget to upload some changed files.

There are better tools to automate this process like rsync or lftp, but they are not the easiest to use. Kirby Deploy wraps lftp, provides good defaults and ships you around the edges.

Warning

This tool is in it's early stages. Use at your own risk and create a backup of your remote/local data before you apply it.

Demo
----

[](#demo)

[![Example](./.github/kirby-deploy-demo.svg)](./.github/kirby-deploy-demo.svg)

Features
--------

[](#features)

- 📡 Uses ftp (no SSH-access required)
- 🌟 Only upload changed files
- 🗂️ Push or pull content to sync your local development
- 🚧 Displays a maintenance note on your website during deployment
- 🧹 Clears the cache after deployment

Installation
------------

[](#installation)

Prerequisites: install [lftp](https://lftp.yar.ru/). If you are using windows, install lftp in WSL (your code doesn't have to be located in WSL).

Install the Kirby plugin

```
composer require arnoson/kirby-deploy
```

Install the CLI

```
npm install kirby-deploy
```

Usage
-----

[](#usage)

Setup your [config](#config) and deploy your website. All commands will start a dry run giving you an overview of which files would be modified or deleted.

```
npx kirby-deploy
```

The content, languages and accounts folder are **not** uploaded, to prevent you from messing up your production website at a later stage. So for the first time deployment you also have to run:

```
npx kirby-deploy content-push
npx kirby-deploy accounts-push
npx kirby-deploy languages-push // If you have a multi-language setup
```

See the `/example` for a more detailed setup with `.env` files and npm scripts.

Config
------

[](#config)

### Basic

[](#basic)

```
// kirby-deploy.config.js

import { defineConfig } from 'kirby-deploy'
export default defineConfig({
  // Ftp credentials
  host: 'ftp://example.com',
  user: 'user',
  password: '********',

  // If your website is located in a subfolder on your ftp accounts root folder,
  // like `./web/example.com`
  remoteDir: './',

  // The URL to your website
  url: 'https://example.com',

  // Wether or not to check if the `composer.lock` file has changed to speed
  // up deployment.
  checkComposerLock: true,

  // Wether ot not call webhooks to set your website in maintenance mode during
  // deployment and clear the pages cache afterwards.
  callWebhooks: true,
  // A secret token to protect the web hooks.
  token: 'my_secret_token',
})
```

Note: don't hardcode your ftp credentials in the config, use an `.env` file instead. See the `/example` folder.

### Advanced

[](#advanced)

```
// kirby-deploy.config.js

import { defineConfig } from 'kirby-deploy'
export default defineConfig({
  // The default folder structure is 'flat' which is Kirby's
  // default structure. But you can also use:
  // - 'public' (https://getkirby.com/docs/guide/configuration/custom-folder-setup#public-and-private-folder-setup)
  // - 'composer' (https://github.com/getkirby/composerkit)
  folderStructure: 'composer',
  // ...or define a custom structure
  folderStructure: {
    content: 'content',
    media: 'public/media',
    accounts: 'storage/accounts',
    sessions: 'storage/sessions',
    cache: 'storage/cache',
    logs: 'storage/logs',
    site: 'site',
  }),

  // Excluding additional files an folders from syncing. Uses lftp's exclude
  // and exclude-glob.
  exclude: ['^my-excluded-folder/'],
  excludeGlob: ['*.ts'],
  // Include files and folders that are matched by the exclude and exclude-glob.
  include: ['^my-included-folder/'],
  includeGlob: ['*-include.ts'],

  // Show additional information, useful for debugging.
  verbose: true,

  // Transfer all files unconditionally, ignoring timestamps and cache. Useful
  // when the remote is in an unknown state and you want to restore it from scratch.
  force: false,

  // Additional lftp settings.
  lftpSettings: { 'ftp:ssl-force': true },

  // Additional lftp flags.
  lftpFlags: ['--no-perms'],
}
```

Commands
--------

[](#commands)

Caution

`deploy` and all `push` commands will overwrite remote files or delete them if they don't exist locally. Likewise all `pull` commands will overwrite local files or delete them.

### 🚀 Deploy

[](#-deploy)

Upload your website to the server.

```
npx kirby-deploy
```

Use `--force` to transfer all files unconditionally, skipping timestamp and cache checks. Useful when the remote is in an unknown state and you want to restore it from scratch.

```
npx kirby-deploy --force
```

### 🗂️ Content

[](#️-content)

#### Push

[](#push)

Upload your local content folder to your website.

```
npx kirby-deploy content-push
```

#### Pull

[](#pull)

Download the content folder from your website.

```
npx kirby-deploy content-pull
```

All content commands also support `--force`:

```
npx kirby-deploy content-push --force
npx kirby-deploy content-pull --force
```

### 🔑 Accounts

[](#-accounts)

#### Push

[](#push-1)

Upload your local accounts folder (including `.htpasswd`) to your website.

```
npx kirby-deploy accounts-push
```

#### Pull

[](#pull-1)

Download the accounts folder (including `.htpasswd`) from your website.

```
npx kirby-deploy accounts-pull
```

All accounts commands also support `--force`:

```
npx kirby-deploy accounts-push --force
npx kirby-deploy accounts-pull --force
```

### 🌍 Languages

[](#-languages)

#### Push

[](#push-2)

Upload your local languages folder to your website.

```
npx kirby-deploy languages-push
```

#### Pull

[](#pull-2)

Download the languages folder from your website.

```
npx kirby-deploy languages-pull
```

All languages commands also support `--force`:

```
npx kirby-deploy languages-push --force
npx kirby-deploy languages-pull --force
```

Troubleshooting
---------------

[](#troubleshooting)

If you can't connect to your ftp server, try connecting with lftp directly to see if this is a general issue with lftp or with this tool.

Try listing e.g. your directory.

```
lftp
SET ftp:ssl-force true
open ftp://example.com
user user_name password
ls
```

Roadmap
-------

[](#roadmap)

- Allow setting lftp flags in config
- Better error handling
- Test `sftp`, right now I only use it for `ftps`

Credits
-------

[](#credits)

Thanks to

- [lftp](https://lftp.yar.ru/)
- [rploy](https://github.com/jongacnik/rploy)

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance78

Regular maintenance activity

Popularity18

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~73 days

Recently: every ~1 days

Total

11

Last Release

96d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6d95ad9b77de39a85a0f39a1cc84535de5affc9aa1150862252681972f4215d9?d=identicon)[arnoson](/maintainers/arnoson)

---

Top Contributors

[![arnoson](https://avatars.githubusercontent.com/u/15122993?v=4)](https://github.com/arnoson "arnoson (1 commits)")

### Embed Badge

![Health badge](/badges/arnoson-kirby-deploy/health.svg)

```
[![Health](https://phpackages.com/badges/arnoson-kirby-deploy/health.svg)](https://phpackages.com/packages/arnoson-kirby-deploy)
```

###  Alternatives

[getkirby/cms

The Kirby core

1.5k584.8k474](/packages/getkirby-cms)[medienbaecker/kirby-modules

Easily add modules to your pages

895.5k1](/packages/medienbaecker-kirby-modules)[oblik/kirby-git

Shows you Git changes in the Kirby panel and allows you to add/commit/push them, manually or automatically.

8310.4k](/packages/oblik-kirby-git)[pju/kirby-webhook-field

A Kirby 3 plugin providing a field to easily use webhooks, e.g. for deploying your site to services such as Netlify

336.1k](/packages/pju-kirby-webhook-field)[johannschopplich/kirby-content-translator

DeepL & AI-powered content translation for Kirby CMS

2010.8k](/packages/johannschopplich-kirby-content-translator)[medienbaecker/kirby-alter

242.1k](/packages/medienbaecker-kirby-alter)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)