Notifer CLI

Coming Soon - Planned for v1.1

The CLI tool is not yet available. It is planned for release in v1.1 (Q1 2026). This documentation describes the planned features and interface. In the meantime, you can use HTTP requests with cURL to interact with the Notifer API.

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

Open Source

When released, the CLI will be 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]`

# 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 1

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

# Combined options
notifer publish deployments "Build #123 completed" \
  --title "Build Success" \
  --priority 2 \
  --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: 2                     │
╰─────────────────────────────────╯

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        │
╰─────────────────────────────╯

P1 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":1,"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 2 \
            --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 1 \
            --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 2 \
          --api-key $NOTIFER_API_KEY \
          --server https://app.notifer.io
      else
        notifer publish deployments "Deploy failed!" \
          --priority 1 \
          --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 2 \
    --tags "deployment,success" \
    --api-key "$API_KEY" \
    --server "$SERVER"
else
  notifer publish deployments "Deploy failed!" \
    --title "Deploy Failed" \
    --priority 1 \
    --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 1

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 <= 2) | .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

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​

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