CLI is a command-line interface for Yorkie. You can use CLI to manage your projects, documents or to start the server.

Getting started

Let's get started with the CLI. There are two ways to install the CLI: pre-built binaries and Homebrew.

Install pre-built binaries

The easiest way to install Yorkie is from pre-built binaries:

  1. Download the compressed archive file for your platform from Releases.
  2. Unpack the archive file. This results in a directory containing the binaries.
  3. Add the executable binaries to your PATH. For example, rename and/or move the binaries to a directory in your PATH (like /usr/local/bin), or add the directory created from the previous step to your PATH.
  4. Test if Yorkie is in your PATH in shell:
$ yorkie version
Yorkie: 0.3.5
Commit: ...
Go: ...
Build date: ...

Install via Homebrew

Homebrew is a free and open-source package management system for Mac OS X. Install the official Yorkie formula in Terminal.

To update Yorkie to the latest version, update Homebrew first.

$ brew update

Now, install Yorkie.

$ brew install yorkie

Verify that the installation worked by opening a new Terminal session and trying Yorkie's available subcommands.

$ yorkie version
Yorkie: 0.3.5
Commit: ...
Go: ...
Build date: ...


Yorkie is just a single command-line application yorkie, which takes a subcommand such as server.

The Yorkie CLI is a well-behaved command-line application. In erroneous cases, a non-zero exit status will be returned. It also responds to -h and ---help as you'd most likely expect.

To get help for any specific command, pass the -h flag to the relevant subcommand. For example, to see help about the server subcommand:

$ yorkie server --help
Start Yorkie server
yorkie server [options] [flags]
--auth-webhook-cache-auth-ttl duration TTL value to set when caching authorized webhook response. (default 10s)
--auth-webhook-cache-size int The cache size of the authorization webhook. (default 5000)
--auth-webhook-cache-unauth-ttl duration TTL value to set when caching unauthorized webhook response. (default 10s)
--auth-webhook-max-retries uint Maximum number of retries for an authorization webhook. (default 10)
--auth-webhook-max-wait-interval duration Maximum wait interval for authorization webhook. (default 3s)
--backend-admin-password string The password of the default admin. (default "admin")
--backend-admin-token-duration duration The duration of the admin authentication token. (default 168h0m0s)
--backend-admin-user string The name of the default admin user, who has full permissions. (default "admin")
--backend-secret-key string The secret key for signing authentication tokens for admin users. (default "yorkie-secret")
--backend-snapshot-interval int Interval of changes to create a snapshot. (default 1000)
--backend-snapshot-threshold int Threshold that determines if changes should be sent with snapshot when the number of changes is greater than this value. (default 500)
--backend-snapshot-with-purging-changes Whether to delete previous changes when the snapshot is created.
--backend-use-default-project Whether to use the default project. Even if public key is not provided from the client, the default project will be used for the request. (default true)
--client-deactivate-threshold string Deactivate threshold of clients in specific project for housekeeping. (default "24h")
-c, --config string Config path
--enable-pprof Enable runtime profiling data via HTTP server.
--etcd-dial-timeout duration ETCD's dial timeout (default 5s)
--etcd-endpoints strings Comma separated list of etcd endpoints
--etcd-lock-lease-time duration ETCD's lease time for lock (default 30s)
--etcd-password string ETCD's password
--etcd-username string ETCD's user name
-h, --help help for server
--hostname string Yorkie Server Hostname
--housekeeping-candidates-limit-per-project int candidates limit per project for a single housekeeping run (default 500)
--housekeeping-interval duration housekeeping interval between housekeeping runs (default 30s)
-l, --log-level string Log level: debug, info, warn, error, panic, fatal (default "info")
--mongo-connection-timeout duration Mongo DB's connection timeout (default 5s)
--mongo-connection-uri string MongoDB's connection URI
--mongo-ping-timeout duration Mongo DB's ping timeout (default 5s)
--mongo-yorkie-database string Yorkie's database name in MongoDB (default "yorkie-meta")
--profiling-port int Profiling port (default 11102)
--rpc-cert-file string RPC certification file's path
--rpc-key-file string RPC key file's path
--rpc-max-requests-bytes uint Maximum client request size in bytes the server will accept. (default 4194304)
--rpc-port int RPC port (default 11101)


To use admin commands, you need to log in to the server. You can log in to the server using the login subcommand:

$ yorkie login -u <username> -p <password>

Username and password are the same as the ones you used to log in to the dashboard.

If you are using the self-hosted server, default username and password are admin and admin.


Project represents your service or application in Yorkie. Separate Projects can exist within a single application. You can add more Projects as needed, for example, if you want to manage auth webhook and documents for specific purposes.

To manage Projects, you can use the project subcommand:

$ yorkie project
Manage projects
yorkie project [command]
Available Commands:
create Create a new project
ls List all projects
update Update a project
-h, --help help for project
Use "yorkie project [command] --help" for more information about a command.

Listing Projects

You can list Projects on the server using ls.

$ yorkie project ls
default cfurlpq6qdop9v48o0u0 cfurlpq6qdop9v48o0ug [] 24h 15 minutes

Server creates a default project automatically. If you create a Client without apiKey, the Client is created in the default Project.

Creating a Project

You can create a new Project with a name using create.

$ yorkie project create test-project

If you create a Client with public_key of the Project as apiKey, you can manage the Client in the Project.

1const client = new yorkie.Client('', {
2 apiKey: 'cfurtei6qdop9v48o0v0', // public_key of the project

Then Documents attached to the Client are isolated and stored in the Project.

Updating the Project

You can update the Project on the server using update.

yorkie project update [name] [flags]
yorkie project update name [options]
--auth-webhook-url string authorization-webhook update url
--client-deactivate-threshold string client deactivate threshold for housekeeping
-h, --help help for update
--name string new project name

You can update the name of the Project with --name flag.

$ yorkie project update test-project --name new-test-project

Auth Webhook

A webhook is an HTTP POST that is called when something happens. If the Auth Webhook has been configured, when a Server receives a request from a Client, the Server checks if the Client has been authorized for a certain Document by asking an outside service with a REST request.

This page shows how to set up an Auth Webhook. The overall flow is as follows:

(5) response the request (4) handle the request
┌─────────────────┐ ┌──┐
│ │ │ │ (3) response
▼ │ ▼ │ - allowed
┌──────┐ ┌┴─────┤ - reason ┌──────────────┐
│Client├────────────►│Server│◄──────────────┤Outside Server│
└──────┘ (1)request └────┬─┘ └──────────────┘
- token │ ▲
- dockey └──────────────────────┘
(2) call webhook
- token
- dockey
- verb: r or rw

First, We need to pass some tokens (that identify users in the service) when creating a Client:

1const client = new yorkie.Client('', {
2 token: SOME_TOKEN,

This token will be sent to the Server upon every request from the Client.

We can specify an Auth Webhook for the project by update command with the --auth-webhook-url flag:

$ yorkie project update [name] --auth-webhook-url http://localhost:3000/auth-hook

The Server who receives the token calls the given webhook URL before processing the requests.

Here is an example of the webhook requests:

2 "token": "SOME_TOKEN", // token passed by the client
3 "method": "PushPull", // method: ActivateClient, DeactivateClient, AttachDocument, DetachDocument, WatchDocuments
4 documentAttributes: [{
5 key: "DOCUMENT_KEY", // document key
6 verb: "r" // 'r' or 'rw'
7 }]

The outside server should respond like this:

2 "allowed": true, // or false if the given token is not authorized for this document.
3 "reason": "ok" // [optional] reason for this response.

If the server receives a response with allowed: true from the outside server, it handles the request normally, otherwise it sends the codes.Unauthenticated error to the client.

Client Deactivate Threshold

Client Deactivate Threshold is a time duration that determines the time for client deactivation of documents in projects. Deactivating the client and detaching it from documents is needed to increase the efficiency of GC removing CRDT tombstones. For more information about GC, please refer to Garbage Collection.

You can set client deactivate threshold of the project with --client-deactivate-threshold flag.

$ yorkie project update test-project --client-deactivate-threshold 1h30m20s

Setting the client deactivation threshold to 1h30m20s will deactivate clients that have been inactive for 1 hour, 30 minutes, and 20 seconds but still remained activated. This will help document GC by not counting deactivated client's document sequence.