Criptocracia CLI client to connect with Electoral Commission

A command-line interface for managing elections, voters, and candidates through the Electoral Commission gRPC API.

Installation

1. Clone the repository
2. Build the project:

cargo build --release

3. The binary will be available at target/release/eccli

Usage

The CLI connects to a gRPC server (default: http://127.0.0.1:50001) and provides commands for election management.

Global Options

• --server <URL>: Specify the gRPC server URL (default: http://127.0.0.1:50001)

Commands

Create Election

Create a new election with candidates.

eccli create-election --name "My Election" --start-time 60 --duration 3600 --candidates-file candidates.json

Parameters:

• --name, -n: Name of the election
• --start-time: Start time in seconds since epoch, or relative seconds from now (e.g., 60 for 1 minute from now)
• --duration: Duration in seconds
• --candidates-file: Path to JSON file containing candidates
• --candidates-json: Candidates as JSON string (alternative to file)

Example candidates.json:

[
  {"id": 1, "name": "Environmental Party"},
  {"id": 2, "name": "Tech Innovation Party"},
  {"id": 3, "name": "Social Justice Party"}
]

Example with JSON string:

eccli create-election --name "Quick Election" --start-time 60 --duration 1800 --candidates-json '[{"id":1,"name":"Candidate A"},{"id":2,"name":"Candidate B"}]'

Add Voter

Add a voter to an existing election.

eccli add-voter --election-id "election-123" --name "John Doe" --pubkey "npub1qqqqqxkw2lgd59lurptz73jc43ksjwevezahh4zg20gvr9hzf2wq8nzqyl"

Parameters:

• --election-id, -e: Election ID
• --name, -n: Voter name
• --pubkey, -p: Public key in hex or npub format

Add Candidate

Add a candidate to an existing election.

eccli add-candidate --election-id "election-123" --candidate-id 4 --name "Independent Candidate"

Parameters:

• --election-id, -e: Election ID
• --candidate-id, -c: Candidate ID (must be unique within the election)
• --name, -n: Candidate name

Get Election Details

Retrieve detailed information about an election.

eccli get-election --election-id "election-123"

Parameters:

• --election-id, -e: Election ID

Example output:

📊 Election Details:
   Name: My Election
   ID: election-123
   Status: Open
   Start: 2024-07-07 15:30:00 UTC
   End: 2024-07-07 16:30:00 UTC
   Total Votes: 0
   Candidates:
     1. Environmental Party (0 votes)
     2. Tech Innovation Party (0 votes)
     3. Social Justice Party (0 votes)

List Voters

List all voters authorized for an election.

eccli list-voters --election-id "election-123" --limit 20 --offset 0

Parameters:

• --election-id, -e: Election ID
• --limit: Maximum number of voters to return (default: 10)
• --offset: Number of voters to skip (default: 0)

List Elections

List all elections.

eccli list-elections --limit 10 --offset 0

Parameters:

• --limit: Maximum number of elections to return (default: 10)
• --offset: Number of elections to skip (default: 0)

Cancel Election

Cancel an existing election.

eccli cancel-election --election-id "election-123"

Parameters:

• --election-id, -e: Election ID

Common Workflows

Creating a Complete Election

1. Create the election:

eccli create-election --name "2025 Student Council Election" --start-time 3600 --duration 7200 --candidates-file candidates.json

2. Add voters:

eccli add-voter --election-id "your-election-id" --name "Alice Wonderland" --pubkey "npub1abc123..."
eccli add-voter --election-id "your-election-id" --name "Bob Marley" --pubkey "deadbeef123..."

3. Verify setup:

eccli get-election --election-id "your-election-id"
eccli list-voters --election-id "your-election-id"

Managing Multiple Elections

1. List all elections:

eccli list-elections --limit 50

2. Get details for specific elections:

eccli get-election --election-id "election-1"
eccli get-election --election-id "election-2"

Bulk Operations

For adding multiple voters, you can use shell scripting:

#!/bin/bash
ELECTION_ID="your-election-id"

# Read from CSV file
while IFS=',' read -r name pubkey; do
    eccli add-voter --election-id "$ELECTION_ID" --name "$name" --pubkey "$pubkey"
done < voters.csv

Time Formats

The --start-time parameter accepts two formats:

1. Relative time (values < 1,000,000,000): Seconds from now

   • 60 = 1 minute from now
   • 3600 = 1 hour from now
   • 86400 = 24 hours from now

2. Absolute time (values ≥ 1,000,000,000): Unix timestamp

   • 1720368600 = Specific date/time in Unix timestamp format

Error Handling

The CLI provides clear error messages for common issues:

• Connection errors: Check if the gRPC server is running and accessible
• Invalid election ID: Ensure the election exists
• Invalid JSON: Verify the syntax of candidate JSON files
• Duplicate candidates: Candidate IDs must be unique within an election
• Missing parameters: All required parameters must be provided

Examples

Sample candidates.json

[
  {"id": 1, "name": "Environmental Party"},
  {"id": 2, "name": "Tech Innovation Party"},
  {"id": 3, "name": "Libertarian Party"},
  {"id": 4, "name": "Independent Candidate"}
]

Sample voters.csv

Alice Wonderland,npub1qqqqqxkw2lgd59lurptz73jc43ksjwevezahh4zg20gvr9hzf2wq8nzqyl
Bob Marley,00001001063e6bf1b28f6514ac651afef7f51b2a792f0416a5e8273daa9eea6e
Charlie Brown,3f55f3701e9b00dce27ab6cce6cf487fd5c4ba48f46d475926ebf916d53a9db1

Help

For help with any command, use the --help flag:

eccli --help
eccli create-election --help
eccli add-voter --help

Technical Details

• Protocol: gRPC over HTTP
• Authentication: Currently none (administrative access assumed)
• Data formats: JSON for structured data, protobuf for gRPC communication
• Public key formats: Both hex and npub (Nostr public key) formats supported

Development

The CLI is built with:

• Rust: Primary language
• clap: Command-line argument parsing
• tonic: gRPC client
• serde: JSON serialization/deserialization
• chrono: Date/time handling