Skip to content

README.md

Latest commit

 

History

History
234 lines (159 loc) · 5.64 KB

README.md

File metadata and controls

234 lines (159 loc) · 5.64 KB

Synkronus CLI

A command-line interface for interacting with the Synkronus API.

Developer note: after OpenAPI spec changes in ../synkronus/openapi/synkronus.yaml, regenerate the Go client with go generate ./pkg/client.

Features

  • Authentication with JWT tokens
  • App bundle management (download, upload, version management)
  • Data synchronization (push and pull)
  • Data export as Parquet ZIP archives
  • Configuration management

Installation

go install github.com/OpenDataEnsemble/ode/synkronus-cli/cmd/synkronus@latest

Or build from source:

git clone https://github.com/OpenDataEnsemble/ode/synkronus-cli.git
cd synkronus-cli
go build -o bin/synk ./cmd/synkronus

Configuration

By default, the CLI uses a configuration file located at $HOME/.synkronus.yaml.

You can override this in two ways:

  • Per-command: pass --config <path> to read/write a specific config file for that invocation.
  • Persistent "current" config: use synk config use <path> to point the CLI at a specific config file for future runs (this writes a pointer file at $HOME/.synkronus_current).

Example configuration file:

api:
  url: http://localhost:8080
  version: 1.0.0

Multiple endpoints example

# Create separate config files
synk config init -o ~/.synkronus-dev.yaml
synk config init -o ~/.synkronus-prod.yaml

# Point CLI at dev by default
synk config use ~/.synkronus-dev.yaml

# Point CLI at prod by default
synk config use ~/.synkronus-prod.yaml

# Temporarily override for a single command
synk --config ~/.synkronus-dev.yaml status

Shell Completion

The Synkronus CLI includes built-in support for shell completion in bash, zsh, fish, and PowerShell. Use synk completion [bash|zsh|fish|powershell] to generate the completion script. In powershell you can load it directly for the current session with:

.\synk.exe completion powershell | Out-String | Invoke-Expression

Enabling Shell Completion

Bash

# For the current session:
source <(synk completion bash)

# For persistent use (Linux):
sudo synk completion bash > /etc/bash_completion.d/synk

# For persistent use (macOS):
synk completion bash > /usr/local/etc/bash_completion.d/synk

Zsh

# For the current session:
source <(synk completion zsh)

# For persistent use:
echo "[[ $commands[synk] ]] && synk completion zsh > "${fpath[1]}/_synk"" >> ~/.zshrc

Fish

# For the current session:
synk completion fish | source

# For persistent use:
synk completion fish > ~/.config/fish/completions/synk.fish

PowerShell

# For the current session:
synk completion powershell | Out-String | Invoke-Expression

# For persistent use (add to your PowerShell profile):
Add-Content -Path $PROFILE -Value "# Synkronus CLI Completion"
Add-Content -Path $PROFILE -Value "synk completion powershell | Out-String | Invoke-Expression"

Usage

Authentication

# Login to the API
synk login --username your-username

# Check authentication status
synk status

# Logout
synk logout

App Bundle Management

# Get app bundle manifest
synk /app-bundle/download/manifest

# List available app bundle versions
synk app-bundle versions

# Download app bundle files
synk /app-bundle/download --output ./app-bundle

# Download a specific file
synk app-bundle download index.html

# Upload a new app bundle (admin only)
synk app-bundle upload bundle.zip

# Upload without switching the active bundle (stage only), with verbose output
synk app-bundle upload bundle.zip --stage-only --verbose

# Switch to a specific app bundle version (admin only)
synk app-bundle switch 20250507-123456

Data Synchronization

# Pull data from the server
synk sync pull --client-id your-client-id

# Pull with filters
synk sync pull --client-id your-client-id --after-change-id 1234 --schema-types form,submission

# Push data to the server
synk sync push data.json

User management (admin)

# List users with role, last activity timestamp (UTC), and client count (N/A when absent)
synk user list

# Create, delete, reset password, change own password — see synk user --help

Data Export

# Export all observations as a Parquet ZIP archive
synk data export exports.zip

# Export to a specific directory
synk data export ./backups/observations_parquet.zip

License

GPL-2.0-or-later — see LICENSE in this directory.

The rest of the ODE monorepo may use other licenses (for example MIT at the repository root). This applies to synkronus-cli only.

Planned follow-up: replace the yeqown/go-qrcode/writer/standard (gg / freetype) stack with a small stdlib qrcode.Writer implementation so this component can return to a permissive license. See FOLLOWUP-custom-qrcode-writer.md for a ticket-ready summary.

Dev. notes

Build with: go build -o bin/synk.exe ./cmd/synkronus Run with: bin/synk.exe

Icon: configured in versioninfo.json and built with goversioninfo goversioninfo -o cmd/synkronus/resource.syso to create a syso file next to main go file.

Regenerating the OpenAPI client

The Go API client in pkg/client/generated/client.gen.go is generated from:

  • Spec: ../synkronus/openapi/synkronus.yaml
  • Tool: github.com/oapi-codegen/oapi-codegen/v2 (pinned in tools.go)
  • Config: oapi-codegen.yaml

Use:

go generate ./pkg/client

Then verify:

go test ./...

FOSS notes for generation stack

  • oapi-codegen is open source under Apache-2.0.
  • github.com/oapi-codegen/runtime is also open source under Apache-2.0.
  • Apache-2.0 is permissive and compatible with MIT-licensed projects.