fessctl is a command-line interface (CLI) tool to manage Fess via its Admin API.

Fess is an open-source enterprise search server based on OpenSearch. fessctl allows developers and operators to automate and script administrative tasks such as:

• Creating or updating crawler configurations
• Managing users and roles
• Starting or stopping scheduled jobs
• Exporting and importing settings
• Monitoring system health

(Currently under development, more features and improvements are on the way. Stay tuned for updates!)

There are four ways to use fessctl:

fessctl is published to PyPI. Install it with pip, or use pipx / uv tool for an isolated, globally available CLI:

pip install fessctl
# or, for an isolated install:
pipx install fessctl
# or:
uv tool install fessctl

export FESS_ACCESS_TOKEN=your_access_token_here
export FESS_ENDPOINT=https://your-fess-server
export FESS_VERSION=15.8.0

fessctl --help
fessctl ping
fessctl user list

If you prefer a container-based workflow, use the pre-built Docker image:

docker run --rm \
  -e FESS_ENDPOINT=https://your-fess-server \
  -e FESS_ACCESS_TOKEN=your_access_token_here \
  -e FESS_VERSION=15.8.0 \
  ghcr.io/codelibs/fessctl:0.3.0 --help

Run actual commands:

docker run --rm \
  -e FESS_ENDPOINT=https://your-fess-server \
  -e FESS_ACCESS_TOKEN=your_access_token_here \
  -e FESS_VERSION=15.8.0 \
  ghcr.io/codelibs/fessctl:0.3.0 ping

docker run --rm \
  -e FESS_ENDPOINT=https://your-fess-server \
  -e FESS_ACCESS_TOKEN=your_access_token_here \
  -e FESS_VERSION=15.8.0 \
  ghcr.io/codelibs/fessctl:0.3.0 user list

Clone the repository and build the Docker image locally:

git clone https://github.com/codelibs/fessctl.git
cd fessctl
docker build -t fessctl:latest .

Then run with your custom image:

docker run --rm \
  -e FESS_ENDPOINT=https://your-fess-server \
  -e FESS_ACCESS_TOKEN=your_access_token_here \
  -e FESS_VERSION=15.8.0 \
  fessctl:latest --help

For development or when you need to modify the source code:

• Python 3.13+
• uv (recommended for environment setup)

git clone https://github.com/codelibs/fessctl.git
cd fessctl
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uv pip install -e src

export FESS_ACCESS_TOKEN=your_access_token_here
export FESS_ENDPOINT=https://your-fess-server
export FESS_VERSION=15.8.0

fessctl --help
fessctl ping
fessctl user list
fessctl webconfig create --name TestConfig --url https://test.config.com/

All four methods require the following environment variables:

• FESS_ENDPOINT: The URL of your Fess server's API endpoint (default: http://localhost:8080)
• FESS_ACCESS_TOKEN: Bearer token for API authentication (required)
• FESS_VERSION: Target Fess version for API compatibility (default: 15.8.0). Set this to match your Fess server. Fess 14.x and 15.x are supported; the value controls version-specific behavior such as HTTP methods for CRUD operations and the health-check endpoint (/api/v1/health for versions before 15.7, /api/v2/health for 15.7 and later).

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Pull requests are welcome! Feel free to open issues or discussions to suggest features, report bugs, or ask questions.