Notifer CLI¶

The Notifer CLI is an open-source command-line tool for interacting with Notifer. It allows you to publish messages, subscribe to topics, manage API keys, and configure topics - all from the terminal.

Open Source

The CLI is open source and available at github.com/nexolab-projects/notifer-cli

Installation¶

Install via pip:

pip install notifer-cli

Or install from source:

git clone https://github.com/nexolab-projects/notifer-cli.git
cd notifer-cli
pip install -e .

Verify installation:

notifer --version

Quick Start¶

1. Authenticate¶

# Option 1: Login with email/password
notifer login user@example.com

# Option 2: Use API key
notifer config set api-key noti_your_key_here

2. Create a Topic¶

Topics Must Exist Before Publishing

You must create a topic before publishing messages to it. Topics are NOT auto-created.

notifer topics create my-topic --description "My first topic"

3. Publish a Message¶

notifer publish my-topic "Hello from CLI!"

notifer subscribe my-topic

Commands Reference¶

Configuration¶

`notifer config init`¶

Create a new configuration file at ~/.notifer.yaml:

notifer config init

`notifer config show`¶

Display current configuration:

notifer config show

Output:

server: https://app.notifer.io
api_key: noti_abc...
email: user@example.com
defaults:
  priority: 3
  tags: []

`notifer config set <key> <value>`¶

Set a configuration value:

# Set API key
notifer config set api-key noti_your_key_here

# Set email
notifer config set email user@example.com

Valid keys: api-key, email

`notifer config get <key>`¶

Get a configuration value:

notifer config get api-key

Authentication¶

`notifer login [email]`¶

Login with email and password. Stores JWT tokens in ~/.notifer.yaml:

# With email as argument
notifer login user@example.com
# Password: ********

# Or prompted for both
notifer login
# Email: user@example.com
# Password: ********

Output:

╭─────────── Login Successful ───────────╮
│ ✓ Logged in as user@example.com        │
│                                        │
│ Username: john_doe                     │
│ Tier: pro                              │
│ Tokens saved to: ~/.notifer.yaml       │
╰────────────────────────────────────────╯

`notifer logout`¶

Clear stored credentials:

notifer logout

Publishing Messages¶

`notifer publish <topic> <message> [OPTIONS]`¶

Publish a message to a topic:

notifer publish my-topic "Hello World!"

Options:

Option	Description
`--title, -t`	Message title
`--priority, -p`	Priority level (1-5, default: 3)
`--tags`	Comma-separated tags
`--api-key`	Override API key
`--server`	Override server URL

Examples:

# Basic message
notifer publish alerts "Server is up"

# With title and priority
notifer publish alerts "Server is down!" \
  --title "Critical Alert" \
  --priority 5

# With tags
notifer publish monitoring "CPU at 95%" \
  --tags "server,cpu,warning"

# Combined options
notifer publish deployments "Build #123 completed" \
  --title "Build Success" \
  --priority 4 \
  --tags "ci,build,success"

# With markdown content
notifer publish updates "# Release v1.2.3\n\n**Features:**\n- New dashboard\n- Bug fixes"

Output:

╭─────────── Published ───────────╮
│ ✓ Message published to alerts   │
│                                 │
│ ID: msg_abc123xyz               │
│ Timestamp: 2025-12-15T10:30:00Z │
│ Priority: 4                     │
╰─────────────────────────────────╯

Error Handling:

If the topic doesn't exist:

✗ Error: Topic 'nonexistent' not found. Create the topic first via the web app, API, or CLI before publishing messages.

Subscribing to Topics¶

`notifer subscribe <topics> [OPTIONS]`¶

Subscribe to a topic and receive messages in real-time via SSE:

notifer subscribe my-topic

Options:

Option	Description
`--output, -o`	Save messages to file (JSONL format)
`--since`	Only show messages since timestamp (ISO format)
`--json`	Output raw JSON (no formatting)
`--api-key`	Override API key
`--server`	Override server URL

Examples:

# Basic subscription
notifer subscribe alerts

# Save to file
notifer subscribe alerts --output messages.jsonl

# Raw JSON output (for piping)
notifer subscribe alerts --json

# Pipe to jq
notifer subscribe alerts --json | jq '.message'

# Messages since specific time
notifer subscribe alerts --since "2025-12-15T00:00:00Z"

Output (formatted):

╭───────── Listening ─────────╮
│ Subscribed to: alerts       │
│ Press Ctrl+C to stop        │
╰─────────────────────────────╯

P5 Critical Alert (2025-12-15 10:30:00)
Server is down!
Tags: server, critical
────────────────────────────────────────────────────────

P3 Deploy (2025-12-15 10:31:15)
Deployment completed successfully
Tags: ci, deploy
────────────────────────────────────────────────────────

Output (JSON):

{"id":"msg_abc123","topic":"alerts","message":"Server is down!","title":"Critical Alert","priority":5,"tags":["server","critical"],"timestamp":"2025-12-15T10:30:00Z"}

JSONL file format:

{"id":"msg_abc123","topic":"alerts","message":"Hello","timestamp":"2025-12-15T10:30:00Z"}
{"id":"msg_def456","topic":"alerts","message":"World","timestamp":"2025-12-15T10:31:00Z"}

Topic Management¶

`notifer topics list [OPTIONS]`¶

List topics:

# List all public topics
notifer topics list

# List only your topics
notifer topics list --mine

# Limit results
notifer topics list --limit 10

Output:

                              Topics
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Name        ┃ Access      ┃ Messages ┃ Subscribers ┃ Description      ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ alerts      │ 🌍 Public   │ 1234     │ 56          │ System alerts    │
│ deployments │ 🔒 Private  │ 89       │ 12          │ CI/CD events     │
│ monitoring  │ 🌍 Public   │ 567      │ 23          │ Server metrics   │
└─────────────┴─────────────┴──────────┴─────────────┴──────────────────┘

`notifer topics get <name>`¶

Get detailed information about a topic:

notifer topics get alerts

Output:

╭─────────── Topic: alerts ───────────╮
│ Name: alerts                        │
│ Access: 🌍 Public                   │
│ Discoverable: Yes                   │
│ Messages: 1234                      │
│ Subscribers: 56                     │
│ Created: 2025-11-01 10:00           │
│                                     │
│ Description:                        │
│ System alerts and notifications     │
╰─────────────────────────────────────╯

`notifer topics create <name> [OPTIONS]`¶

Create a new topic:

notifer topics create my-topic

Options:

Option	Description
`--description, -d`	Topic description
`--private`	Make topic private
`--no-discover`	Hide from browse/discovery

Examples:

# Public topic
notifer topics create alerts --description "System alerts"

# Private topic
notifer topics create private-alerts --private --description "Internal alerts"

# Hidden from discovery
notifer topics create hidden-topic --no-discover

`notifer topics delete <topic_id>`¶

Delete a topic permanently:

notifer topics delete abc123

You'll be prompted for confirmation:

Permanently delete topic abc123? This cannot be undone! [y/N]: y
✓ Topic deleted: abc123

API Key Management¶

`notifer keys list`¶

List all your API keys:

notifer keys list

Output:

                                    API Keys
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Name       ┃ Prefix     ┃ Scopes          ┃ Requests ┃ Status    ┃ Created    ┃ Last Used  ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ ci-deploy  │ noti_abc   │ publish, topics │ 1234     │ ✓ Active  │ 2025-11-01 │ 2025-12-15 │
│ monitoring │ noti_def   │ *               │ 567      │ ✓ Active  │ 2025-11-02 │ 2025-12-14 │
│ old-key    │ noti_ghi   │ publish         │ 89       │ ✗ Revoked │ 2025-10-01 │ 2025-10-15 │
└────────────┴────────────┴─────────────────┴──────────┴───────────┴────────────┴────────────┘

`notifer keys create <name> [OPTIONS]`¶

Create a new API key:

notifer keys create "CI/CD Pipeline"

Options:

Option	Description
`--description, -d`	Key description
`--scopes, -s`	Comma-separated scopes (default: `*`)
`--expires`	Expiration date (ISO format)

Examples:

# Full access key
notifer keys create "Full Access"

# Limited scopes
notifer keys create "CI/CD" --scopes "publish,topics:read"

# With expiration
notifer keys create "Temp Key" --expires "2025-12-31T23:59:59Z"

Output:

╭─────────────── API Key Created ───────────────╮
│ ⚠ IMPORTANT: Save this key now - it won't    │
│ be shown again!                               │
│                                               │
│ noti_abc123def456ghi789jkl012mno345pqr        │
│                                               │
│ Name: CI/CD Pipeline                          │
│ Scopes: publish, topics:read                  │
│ Created: 2025-12-15T10:30:00                  │
╰───────────────────────────────────────────────╯

Save this key to config file? [y/N]: y
✓ Key saved to ~/.notifer.yaml

`notifer keys revoke <key_id>`¶

Revoke an API key (keeps for audit history):

notifer keys revoke abc123

`notifer keys delete <key_id>`¶

Permanently delete an API key:

notifer keys delete abc123

Configuration File¶

The CLI stores configuration in ~/.notifer.yaml:

# Authentication (use one of the following)
api_key: noti_abc123def456...

# OR JWT tokens (from login)
email: user@example.com
access_token: eyJhbGciOiJIUzI1NiIs...
refresh_token: eyJhbGciOiJIUzI1NiIs...

# Default options
defaults:
  priority: 3
  tags: []

Priority Order¶

Configuration values are resolved in this order (highest priority first):

Command-line options (--api-key)
Environment variables (NOTIFER_API_KEY)
Configuration file (~/.notifer.yaml)
Defaults

Environment Variables¶

Override API key with environment variable:

export NOTIFER_API_KEY=noti_abc123...

notifer publish my-topic "Hello"

Variable	Description
`NOTIFER_API_KEY`	API key for authentication

Use Cases¶

CI/CD Integration¶

GitHub Actions¶

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Notifer CLI
        run: pip install notifer-cli

      - name: Deploy
        run: ./deploy.sh

      - name: Notify Success
        if: success()
        run: |
          notifer publish deployments "Deploy succeeded" \
            --title "Deploy Success" \
            --priority 4 \
            --tags "ci,deploy,success" \
            --api-key ${{ secrets.NOTIFER_API_KEY }} \
            --server https://app.notifer.io

      - name: Notify Failure
        if: failure()
        run: |
          notifer publish deployments "Deploy failed!" \
            --title "Deploy Failed" \
            --priority 5 \
            --tags "ci,deploy,error" \
            --api-key ${{ secrets.NOTIFER_API_KEY }} \
            --server https://app.notifer.io

GitLab CI¶

deploy:
  script:
    - pip install notifer-cli
    - ./deploy.sh
  after_script:
    - |
      if [ "$CI_JOB_STATUS" == "success" ]; then
        notifer publish deployments "Deploy succeeded" \
          --priority 4 \
          --api-key $NOTIFER_API_KEY \
          --server https://app.notifer.io
      else
        notifer publish deployments "Deploy failed!" \
          --priority 5 \
          --api-key $NOTIFER_API_KEY \
          --server https://app.notifer.io
      fi

Shell Scripts¶

Deployment Script¶

#!/bin/bash
# deploy.sh

API_KEY="noti_abc123..."
SERVER="https://app.notifer.io"

# Notify start
notifer publish deployments "Deploy started for $VERSION" \
  --priority 3 \
  --tags "deployment,start" \
  --api-key "$API_KEY" \
  --server "$SERVER"

# Run deployment
./deploy-script.sh
EXIT_CODE=$?

# Notify result
if [ $EXIT_CODE -eq 0 ]; then
  notifer publish deployments "Deploy succeeded!" \
    --title "Deploy Success" \
    --priority 4 \
    --tags "deployment,success" \
    --api-key "$API_KEY" \
    --server "$SERVER"
else
  notifer publish deployments "Deploy failed!" \
    --title "Deploy Failed" \
    --priority 5 \
    --tags "deployment,failure" \
    --api-key "$API_KEY" \
    --server "$SERVER"
fi

Bash Aliases¶

Add to ~/.bashrc or ~/.zshrc:

# Quick notify alias
alias notify='notifer publish notifications'

# Usage
notify "Task completed!"

# Notify on command completion
long-running-command && notify "Success!" || notify "Failed!" --priority 5

Monitoring¶

Log Collector¶

#!/bin/bash
# Collect messages and save to file
notifer subscribe alerts,errors \
  --output /var/log/notifer-alerts.jsonl \
  --api-key "$NOTIFER_API_KEY"

Process Messages with jq¶

# Stream and filter high-priority messages
notifer subscribe alerts --json | jq -r 'select(.priority >= 4) | .message'

# Count messages per topic
notifer subscribe alerts,deployments --json | jq -s 'group_by(.topic) | map({topic: .[0].topic, count: length})'

Troubleshooting¶

Connection Issues¶

# Test server connectivity
curl https://app.notifer.io/health

# Use verbose output for debugging
notifer --debug publish my-topic "Test"

Authentication Issues¶

# Check current config
notifer config show

# Re-login
notifer logout
notifer login

# Or set new API key
notifer config set api-key noti_new_key_here

Common Errors¶

Error	Solution
`Topic not found`	Create the topic first: `notifer topics create <name>`
`Unauthorized`	Check API key or login again
`Connection refused`	Verify server URL in config
`Invalid credentials`	Re-run `notifer login`

Next Steps¶

HTTP Publishing - Direct cURL examples
Python SDK - Publish from Python code
API Keys - Learn about API authentication
SSE Subscriptions - Technical details on real-time subscriptions

Notifer CLI¶

Installation¶

Quick Start¶

1. Authenticate¶

2. Create a Topic¶

3. Publish a Message¶

4. Subscribe to Messages¶

Commands Reference¶

Configuration¶

notifer config init¶

notifer config show¶

notifer config set <key> <value>¶

notifer config get <key>¶

Authentication¶

notifer login [email]¶

notifer logout¶

Publishing Messages¶

notifer publish <topic> <message> [OPTIONS]¶

Subscribing to Topics¶

notifer subscribe <topics> [OPTIONS]¶

Topic Management¶

notifer topics list [OPTIONS]¶

notifer topics get <name>¶

notifer topics create <name> [OPTIONS]¶

notifer topics delete <topic_id>¶

API Key Management¶

notifer keys list¶

notifer keys create <name> [OPTIONS]¶

notifer keys revoke <key_id>¶

notifer keys delete <key_id>¶

Configuration File¶

Priority Order¶

Environment Variables¶

Use Cases¶

CI/CD Integration¶

GitHub Actions¶

GitLab CI¶

Shell Scripts¶

Deployment Script¶

Bash Aliases¶

Monitoring¶

Log Collector¶

Process Messages with jq¶

Troubleshooting¶

Connection Issues¶

Authentication Issues¶

Common Errors¶

Next Steps¶

`notifer config init`¶

`notifer config show`¶

`notifer config set <key> <value>`¶

`notifer config get <key>`¶

`notifer login [email]`¶

`notifer logout`¶

`notifer publish <topic> <message> [OPTIONS]`¶

`notifer subscribe <topics> [OPTIONS]`¶

`notifer topics list [OPTIONS]`¶

`notifer topics get <name>`¶

`notifer topics create <name> [OPTIONS]`¶

`notifer topics delete <topic_id>`¶

`notifer keys list`¶

`notifer keys create <name> [OPTIONS]`¶

`notifer keys revoke <key_id>`¶

`notifer keys delete <key_id>`¶