Skip to content

CLI Tool

The Notifer CLI provides a simple command-line interface for publishing and subscribing to topics.

Installation

Install via pip:

pip install notifer-cli

Or install from source:

git clone https://github.com/your-org/notifer.git
cd notifer/cli
pip install -e .

Verify installation:

notifer --version

Quick Start

Publish a Message

notifer publish my-topic "Hello from CLI!"

Subscribe to a Topic

notifer subscribe my-topic

Configuration

Initialize Config File

Create a config file at ~/.notifer.yaml:

notifer config init

View Configuration

notifer config show

Set Configuration Values

# Set server URL
notifer config set server https://app.notifer.io

# Set API key
notifer config set api-key noti_your_key_here

Get Configuration Value

notifer config get server

Publishing Messages

Basic Publishing

notifer publish my-topic "Your message here"

With Title

notifer publish my-topic "Deployment completed" --title "Deploy Success"

With Priority

notifer publish alerts "Server is down!" --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 3 \
  --tags "ci,build,success"

Using API Key

notifer publish private-topic "Secret message" \
  --api-key noti_your_key_here

Custom Server

notifer publish my-topic "Message" \
  --server http://localhost:8080

Subscribing to Topics

Basic Subscription

notifer subscribe my-topic

Output:

🔔 Subscribed to: my-topic
Listening for messages... (Press Ctrl+C to stop)

[2025-11-02 10:30:00] Hello from CLI!
  Priority: 3 | Tags: []

[2025-11-02 10:31:15] 📢 Deploy Success
  Deployment completed successfully
  Priority: 3 | Tags: [ci, deploy]

Subscribe to Multiple Topics

notifer subscribe "alerts,monitoring,deployments"

Save to File

notifer subscribe my-topic --output messages.jsonl

Output format (JSON Lines):

{"id":"msg_abc123","topic":"my-topic","message":"Hello","timestamp":"2025-11-02T10:30:00Z"}
{"id":"msg_def456","topic":"my-topic","message":"World","timestamp":"2025-11-02T10:31:00Z"}

Raw JSON Output

notifer subscribe my-topic --json

Useful for piping to other tools:

notifer subscribe alerts --json | jq '.message'

Messages Since Timestamp

notifer subscribe my-topic --since "2025-11-02T10:00:00Z"

Authentication

Login

notifer login user@example.com

You'll be prompted for your password (hidden input).

Login with Email Prompt

notifer login

Logout

notifer logout

API Key Management

List API Keys

notifer keys list

Output:

┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Name       ┃ Prefix     ┃ Scopes ┃ Requests ┃ Status ┃ Created          ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ ci-deploy  │ noti_abc   │ *      │ 1234     │ active │ 2025-11-01 10:00 │
│ monitoring │ noti_def   │ *      │ 567      │ active │ 2025-11-02 15:30 │
└────────────┴────────────┴────────┴──────────┴────────┴──────────────────┘

Create API Key

notifer keys create ci-deploy \
  --description "CI/CD pipeline key" \
  --scopes "publish,subscribe"

Options:

  • --description - Key description
  • --scopes - Comma-separated scopes (default: * for all)
  • --expires - Expiration date (ISO 8601 format)

The key will be displayed once - save it securely!

You'll be prompted to save it to your config file.

Revoke API Key

notifer keys revoke key_id_here

Revoked keys can be re-enabled.

Delete API Key

notifer keys delete key_id_here

Permanently deletes the key (cannot be undone).

Topic Management

List Topics

# List all public topics
notifer topics list

# List only your topics
notifer topics list --mine

# Limit results
notifer topics list --limit 10

Get Topic Details

notifer topics get my-topic

Create Topic

# Public topic
notifer topics create my-new-topic \
  --description "My new topic"

# Private topic
notifer topics create private-topic \
  --description "Private notifications" \
  --private

# Hidden from discovery
notifer topics create hidden-topic \
  --description "Not listed in browse" \
  --no-discover

Delete Topic

notifer topics delete topic_id_here

You'll be prompted for confirmation.

Configuration File Format

The config file (~/.notifer.yaml) stores your settings:

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

Environment Variables

Override config with environment variables:

export NOTIFER_SERVER=https://app.notifer.io
export NOTIFER_API_KEY=noti_your_key_here

notifer publish my-topic "Message"

Shell Integration

Bash Alias

Add to ~/.bashrc:

alias notify='notifer publish notifications'

Usage:

notify "Task completed!"

Command Success/Failure

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

Background Job Notification

# Start job in background
long-running-command &
JOB_PID=$!

# Notify when complete
wait $JOB_PID
notifer publish jobs "Job $JOB_PID completed" --tags "background,complete"

CI/CD Integration

GitHub Actions

name: Deploy
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - 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" \
            --tags "ci,deploy,success" \
            --api-key ${{ secrets.NOTIFER_API_KEY }}

      - 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 }}

GitLab CI

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

Troubleshooting

Connection Issues

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

# Use custom server
notifer publish my-topic "Test" --server http://localhost:8080

Authentication Issues

# Check current config
notifer config show

# Re-login
notifer logout
notifer login

# Or set API key
notifer config set api-key noti_your_new_key

Debug Mode

# Enable verbose output
notifer --debug publish my-topic "Test"

Next Steps