Skip to content

README.md

Latest commit

 

History

History
205 lines (149 loc) · 4.52 KB

README.md

File metadata and controls

205 lines (149 loc) · 4.52 KB
Raw

OpenMarkers CLI

Command-line interface for OpenMarkers — an open-source biomarker and blood test tracker.

Built AI-agent first: structured JSON output, meaningful exit codes, and stdin/pipe support. Interactive TUI for humans as a secondary mode.

Install

Homebrew

brew install nezdemkovski/tap/openmarkers

From source

go install github.com/openmarkers/openmarkers-cli@latest

Binary releases

Download from GitHub Releases.

Quick start

# Authenticate (opens browser for OAuth)
openmarkers auth login

# List your profiles
openmarkers profile list

# View biomarker trends
openmarkers trends 1

# Export a profile as JSON
openmarkers export 1 > backup.json

# Import it back
openmarkers import backup.json --confirm

Commands

Authentication

openmarkers auth login      # OAuth 2.1 PKCE flow (opens browser)
openmarkers auth logout     # Delete stored credentials
openmarkers auth status     # Check authentication status

Login discovers OpenMarkers OAuth Protected Resource metadata from https://openmarkers.app, then uses the shared OpenMarkers auth realm. New logins register a public PKCE client with the exact local callback URL and do not require a client secret.

Profiles

openmarkers profile list
openmarkers profile get <id>
openmarkers profile create --name "Name" --dob 1990-01-15 --sex M
openmarkers profile update <id> --public --handle my-handle
openmarkers profile delete <id>

Biomarkers & Categories

openmarkers biomarker list [--category lipids]
openmarkers biomarker get <id>
openmarkers biomarker create --id custom_test --category custom --unit mg/dL
openmarkers category list

Results

openmarkers result list --profile 1 [--biomarker glucose] [--date-from 2024-01-01]
openmarkers result add --profile 1 --biomarker glucose --date 2024-03-15 --value 95
openmarkers result batch-add --profile 1 --date 2024-03-15 --file results.json
openmarkers result update <id> --value 92
openmarkers result delete <id>

Analytics

openmarkers timeline <profile_id>
openmarkers snapshot <profile_id> --date 2024-03-15
openmarkers trends <profile_id> [--biomarker glucose] [--category lipids]
openmarkers compare <profile_id> --date1 2024-01-01 --date2 2024-06-01
openmarkers correlations <profile_id>
openmarkers bioage <profile_id>
openmarkers analysis <profile_id> [--lang en]

Import & Export

openmarkers export <profile_id>                    # JSON to stdout
openmarkers export 1 > profile.json                # Save to file
openmarkers import profile.json --confirm           # Import from file
cat profile.json | openmarkers import --confirm     # Import from stdin

Public profiles

openmarkers public list            # No auth required
openmarkers public get <handle>

Schema

openmarkers schema                 # Biomarker definitions (no auth required)

Output formats

The CLI defaults to JSON when piped and table format in a terminal.

# Force JSON (for scripting / AI agents)
openmarkers profile list --json

# Force table
openmarkers profile list --output table

# Force plain text
openmarkers profile list --output text

JSON envelope

Success:

{
  "data": [ ... ]
}

Error:

{
  "error": {
    "code": "not_found",
    "message": "Profile not found"
  }
}

Exit codes

Code Meaning
0 Success
1 General error
2 Usage error
3 Authentication required
4 Not found
5 Server error

Configuration

Source Example
Flag --server https://custom.example.com
Env OPENMARKERS_SERVER=https://...
Config ~/.config/openmarkers/config.json
Default https://openmarkers.app

Resolution order: flag > env > config file > default.

Token storage

Credentials are stored securely via OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service) with automatic fallback to a local config file. auth logout also removes legacy client-secret entries from older CLI logins.

Shell completions

# Bash
openmarkers completion bash > /etc/bash_completion.d/openmarkers

# Zsh
openmarkers completion zsh > "${fpath[1]}/_openmarkers"

# Fish
openmarkers completion fish > ~/.config/fish/completions/openmarkers.fish

Development

go build -o openmarkers .
go test ./...
go vet ./...

License

MIT