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:

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:

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:

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:

# 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:

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:

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 when selecting a RemoteControl method or checking its parameter order and return type.
• Read 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.