Metadata-Version: 2.4
Name: fessctl
Version: 0.3.0
Summary: CLI tool to manage Fess using the admin API
Author-email: "CodeLibs, Inc." <info@codelibs.co>
License-Expression: Apache-2.0
Project-URL: Homepage, https://fess.codelibs.org/
Project-URL: Repository, https://github.com/codelibs/fessctl
Project-URL: Issues, https://github.com/codelibs/fessctl/issues
Project-URL: Documentation, https://github.com/codelibs/fessctl#readme
Project-URL: Changelog, https://github.com/codelibs/fessctl/releases
Keywords: fess,search,opensearch,cli,admin,codelibs
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx==0.28.1
Requires-Dist: pyyaml==6.0.2
Requires-Dist: typer[all]==0.16.0
Provides-Extra: dev
Requires-Dist: pytest>=7.1.0; extra == "dev"
Requires-Dist: testcontainers>=3.9.0; extra == "dev"
Requires-Dist: requests>=2.28.0; extra == "dev"
Dynamic: license-file

# FessCTL

[![PyPI version](https://img.shields.io/pypi/v/fessctl.svg)](https://pypi.org/project/fessctl/)
[![Python versions](https://img.shields.io/pypi/pyversions/fessctl.svg)](https://pypi.org/project/fessctl/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/codelibs/fessctl/blob/main/LICENSE)

**fessctl** is a command-line interface (CLI) tool to manage [Fess](https://fess.codelibs.org/) 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:

### Method 1: Install from PyPI (recommended)

`fessctl` is published to [PyPI](https://pypi.org/project/fessctl/). Install it with `pip`,
or use [`pipx`](https://pipx.pypa.io/) / [`uv tool`](https://docs.astral.sh/uv/guides/tools/)
for an isolated, globally available CLI:

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

#### Usage
```bash
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
```

### Method 2: Using Pre-built Docker Image

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

```bash
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:

```bash
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
```

### Method 3: Building Your Own Docker Image

Clone the repository and build the Docker image locally:

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

Then run with your custom image:

```bash
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
```

### Method 4: Install from Source

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

#### Requirements
- Python 3.13+
- [`uv`](https://github.com/astral-sh/uv) (recommended for environment setup)

#### Setup
```bash
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
```bash
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/
```

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

## License

This project is licensed under the Apache License 2.0.
See the [LICENSE](https://github.com/codelibs/fessctl/blob/main/LICENSE) file for details.

## Contributing

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