Competition work, from the terminal
Training a model is only part of a competition workflow. Downloading datasets, uploading predictions, checking submission limits, and finding discussion threads can interrupt the experiment itself. I built Zindi CLI to bring those operations into the same terminal environment as the training code.
The interface is designed for both people and automation. A shell script can read a consistent JSON response, while someone inspecting results manually can request a table. Commands cover competition discovery and participation, data files, submissions, leaderboards, team management, and discussions.
A predictable command contract
The central design choice is a clear boundary between command handling and the HTTP client. Typer defines the commands; a shared client handles requests and translates API behavior into useful results. Configuration resolves an explicit argument, environment setting, or saved default, and responses identify the competition being used.
Successful commands write one JSON document to standard output. Errors carry a code, message, and meaningful process exit status. Progress output stays separate, and noninteractive runs do not wait for a prompt. Those details make the tool practical inside a longer script where an unexpected line of text or blocked prompt could break the workflow.
Working with an imperfect API
Several small decisions address the behavior of the service directly:
- Competition filtering happens locally where server-side query options are unreliable.
- Leaderboard requests follow pagination so an entry can be found beyond the first response.
- Submission files are checked before upload, and an unknown daily submission cap remains unknown.
- Expired authentication can trigger one refresh and retry.
- Diagnostic reads are the default; persistent diagnostic operations require explicit confirmation.
The test suite uses mocked HTTP responses and temporary configuration directories. It covers request errors, pagination, configuration precedence, and command output without submitting to a live competition. CI is configured to run lint and coverage checks across supported Python versions.
Outcome
The result is an installable Python tool that connects the administrative steps around a competition to the experiment workflow. Its strongest feature is consistency: discovery, downloads, submission checks, and failures share a contract that other tools can understand.
The source repository includes installation instructions, command examples, and the test suite.