Skip to main content

FessCTL

PyPI version Python versions License

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!)

Installation and Usage

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

Usage

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

fessctl --help
fessctl ping
fessctl user list

Method 2: Using Pre-built Docker Image

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.9.0 \
  ghcr.io/codelibs/fessctl:0.4.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.9.0 \
  ghcr.io/codelibs/fessctl:0.4.0 ping

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

Method 3: Building Your Own Docker Image

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.9.0 \
  fessctl:latest --help

Method 4: Install from Source

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

Requirements

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

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

Usage

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

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

Environment Variables

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.9.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).

License

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

Contributing

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

Metadata

Release files for fessctl 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fessctl 0.4.0
File Size Uploaded Provenance Actions
fessctl-0.4.0.tar.gz 55.0 kB With provenance Details for fessctl-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fessctl 0.4.0
File Interpreter ABI Platform Actions
fessctl-0.4.0-py3-none-any.whl Python 3 none any Details for fessctl-0.4.0-py3-none-any.whl

Total release size: 140.9 kB

Release files / fessctl-0.4.0.tar.gz

Download URL fessctl-0.4.0.tar.gz
Size 55.0 kB
Tags Source
SHA-256 checksum
How to use checksums
1ce7b2e25397b59ffadff97ee5c719ddeabae85c8d6cadabb0c8af85a09bbbdf
BLAKE2b-256 checksum
How to use checksums
862dd4755c1257a8fd6934f1126eca3390c5053bea5ce7a4cd2fffaacf072516
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Release files / fessctl-0.4.0-py3-none-any.whl

Download URL fessctl-0.4.0-py3-none-any.whl
Size 86.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cb61cd87b74ecdb1fbffa73f71ca116152a460b7bfc90862e2407b985d45bd1c
BLAKE2b-256 checksum
How to use checksums
d8fcac30ae1209bfd1d40058f6d988f3b37cda3abf2c4bc82447ddb6fc51a638
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Security for fessctl 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fessctl-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page