# Limesurvey Skill

> Automate LimeSurvey through the RemoteControl 2 JSON-RPC API. Use for survey discovery, response exports, participant management, invitations, activation, statistics, questions, groups, or other LimeSurvey administration tasks.

- Skill: `olegantonov/limesurvey-skill` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add olegantonov/limesurvey-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/olegantonov/limesurvey-skill/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: olegantonov (https://skillmd.com/u/olegantonov)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/olegantonov/limesurvey-skill

---


# LimeSurvey RemoteControl 2

Use the bundled Python client and CLI to work with LimeSurvey. Resolve every
script and reference path relative to the directory containing this file; do
not assume the current working directory is the skill directory.

## Operating rules

1. Confirm the target LimeSurvey endpoint and survey ID before changing remote
   state. Use list or summary commands first when the target is ambiguous.
2. Treat credentials, participant data, tokens, and responses as sensitive.
   Never print credentials or place them in command arguments, source files, or
   version control.
3. Read-only discovery and exports may proceed when they are within the user's
   request. Adding or deleting data, sending email, activating a survey, or
   changing survey structure requires an explicit request for that action.
4. Before a high-impact operation, report the resolved survey ID and scope.
   Never infer permission to send invitations to all participants or delete
   records from a general request to inspect a survey.
5. Prefer the CLI for supported operations. Use the Python client directly for
   API methods that the CLI does not expose.

## Prerequisites

Set these environment variables in the execution environment:

```bash
export LIMESURVEY_URL='https://survey.example.com/index.php/admin/remotecontrol'
export LIMESURVEY_USER='service_account_username'
export LIMESURVEY_PASSWORD='service_account_password'
```

Use a dedicated least-privilege account. The RemoteControl API must be enabled
on the LimeSurvey instance.

## CLI workflow

Let `SKILL_DIR` be the absolute path of this skill directory.

Start with a read-only command:

```bash
python3 "$SKILL_DIR/scripts/limesurvey.py" list-surveys
python3 "$SKILL_DIR/scripts/limesurvey.py" get-summary 123456
python3 "$SKILL_DIR/scripts/limesurvey.py" list-participants 123456 --limit 100
```

Export responses to an explicit destination:

```bash
python3 "$SKILL_DIR/scripts/limesurvey.py" export-responses 123456 \
  --format csv --completion-status complete -o responses.csv
```

Binary formats such as PDF, XLS, and DOC require `--output`; do not send binary
data to the terminal. CSV and JSON may be written to a file or standard output.

Remote mutations supported by the CLI:

```bash
# Add participants from JSON after checking the file and survey ID
python3 "$SKILL_DIR/scripts/limesurvey.py" add-participants 123456 \
  --file participants.json

# Send invitations only when the user requested email delivery
python3 "$SKILL_DIR/scripts/limesurvey.py" invite-participants 123456 \
  --token-ids 1,2,3

# Activation changes the survey schema and cannot be casually reversed
python3 "$SKILL_DIR/scripts/limesurvey.py" activate-survey 123456
```

Omitting `--token-ids` sends invitations to all eligible pending participants.
Do that only when the user explicitly requested that scope.

## Python client

For methods not exposed by the CLI:

```python
from scripts.limesurvey_client import LimeSurveySession

endpoint = "https://survey.example.com/index.php/admin/remotecontrol"

with LimeSurveySession(endpoint, username, password) as client:
    surveys = client.call("list_surveys", client.session_key)
```

The context manager releases the API session automatically. API-level failures
may be returned as dictionaries containing a `status` key; JSON-RPC, HTTP, and
decoding failures raise `LimeSurveyError`.

For exports:

```python
encoded = client.call("export_responses", client.session_key, survey_id, "csv")
csv_text = client.decode_base64(encoded)

encoded_pdf = client.call(
    "export_statistics", client.session_key, survey_id, "pdf", None, "1"
)
pdf_bytes = client.decode_base64_bytes(encoded_pdf)
```

Use `decode_base64` for UTF-8 text and `decode_base64_bytes` for binary files.

## Reference routing

- Read [references/api_reference.md](references/api_reference.md) when selecting
  a RemoteControl method or checking its parameter order and return type.
- Read [references/examples.md](references/examples.md) for participant imports,
  filtered exports, question management, reporting, and batch examples.
- Consult the official LimeSurvey RemoteControl 2 documentation when the local
  reference does not cover the server version or requested method.

## Error handling

- A `status` result usually means invalid input, insufficient permissions, or
  invalid session state. Report it without retrying a mutation blindly.
- On authentication failure, verify the endpoint and service-account access;
  do not echo the password.
- If a request times out or the session expires, a read-only request may be
  retried once. Recheck remote state before retrying a mutation.
- Preserve exported data only as long as the user's task requires and avoid
  exposing participant information in summaries.