Manage Casdoor from the command line

This guide explains how to install Casdoor CLI, the official command-line interface of Casdoor, and how to manage users and groups with it.

Learning outcomes

Build and install the CLI on macOS or Linux.
Connect the CLI to your Casdoor instance and sign in.
Manage users and groups from the terminal.
Set up a local environment to develop the CLI.

What you need

macOS or Linux. The CLI is tested on Debian 12 and macOS Sonoma.
Go 1.22.0 or later
A system keyring: GNOME Keyring on Linux, Keychain on macOS
A running Casdoor instance and an application for the CLI

cẩn thận

The CLI doesn't run on Windows, including the Windows Subsystem for Linux (WSL). It stores credentials through the Secret Service DBus interface of GNOME Keyring, which WSL doesn't provide.

About the CLI

Feature	Description
Sign-in in the browser	The CLI signs you in with the OAuth 2.0 flow of Casdoor in your browser. It never sees your password
Token storage	The CLI stores tokens in the system keyring. Tokens are never written to disk as plaintext
User management	Create, update, and delete users
Group management	Create, change, and delete groups
Permissions	The CLI controls what a user may do through Casdoor groups, with three built-in roles

The built-in roles are:

Role	Rights
`lector`	Read-only access
`editor`	Can create users, with limited rights to change them
`administrator`	Can create, change, and delete users

Install the CLI

Clone casdoor-cli.

Build and install the CLI.

On macOS:

make build TARGET_OS=darwin && make install TARGET_OS=darwin

On Linux:

make build TARGET_OS=linux && make install TARGET_OS=linux

Add the install directory to your PATH.

In Bash:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

In Zsh:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Check that the CLI runs:
```
casdoor --help
```

Connect the CLI to Casdoor

Create an application for the CLI in Casdoor in one of two ways:
- Load the init_data.json of the casdoor-cli repository. See Initialize and manage data with a file.
- Create and configure the application by hand in the Casdoor admin console.

Run the CLI. On its first run, it asks for a config.yaml with the connection details. Use config.yaml.example of the repository as a template. The required fields are:

application_name: your-app-name
casdoor_endpoint: https://your-casdoor-instance.com
certificate: |
  -----BEGIN CERTIFICATE-----
  Your certificate content here
  -----END CERTIFICATE-----
client_id: your-client-id
client_secret: your-client-secret
organization_name: your-organization
redirect_uri: http://localhost:9000/callback

The CLI stores the configuration, Base64-encoded, in ~/.casdoor-cli/config.yaml and reads it from there afterward.

To sign in, run:

casdoor login

The CLI opens your default browser, where you sign in to Casdoor.

To sign out, run:

casdoor logout

Manage users and groups

The CLI has the following commands:

Usage:
  casdoor [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  groups      Manage Casdoor permissions
  help        Help about any command
  login       Login to your Casdoor account
  logout      Logout from your Casdoor account
  users       Manage Casdoor users

Flags:
  -d, --debug   verbose logging
  -h, --help    help for casdoor

Manage users:

# List users
casdoor users list

# Create a user
casdoor users create

# Update a user
casdoor users update

# Delete a user
casdoor users delete

Manage groups:

# List groups
casdoor groups list

# Create a group
casdoor groups create

# Update a group
casdoor groups update

# Delete a group
casdoor groups delete

Set up a development environment

To work on the CLI itself:

In the casdoor-cli repository, start the local Casdoor environment:
```
docker compose up -d
```
Wait for the Casdoor container to initialize. It restarts several times while it sets up the database.
Create config.yaml at the root of the repository from config.yaml.example, with the settings of the local environment.

Run the CLI from source and sign in with the development credentials that the repository documents:

go run main.go login

Or build and install it first:

make build TARGET_OS=darwin && make install TARGET_OS=darwin  # For macOS
# OR
make build TARGET_OS=linux && make install TARGET_OS=linux    # For Linux

casdoor login

Learning outcomes​

What you need​

About the CLI​

Install the CLI​

Connect the CLI to Casdoor​

Sign in and out​

Manage users and groups​

Set up a development environment​

See also​