January 10, 2026

Command Reference

Complete reference for Routerly commands. All commands follow natural language patterns for readability.

Status: This documentation describes planned v1.0 functionality. Commands may change during development.

Network Definition Commands

Define Network Alias

Create a memorable name for a network range.

routerly define [name] as [CIDR]

Examples:

routerly define home as 192.168.1.0/24
routerly define office-wifi as 10.0.1.0/24
routerly define iot-devices as 192.168.100.0/24

Notes:

Names must be lowercase with optional hyphens
CIDR notation required
Aliases persist across reboots

Remove Network Alias

Delete a network alias.

routerly undefine [name]

Examples:

routerly undefine guest

Warning: Rules using this alias will become invalid and must be updated.

Rule Commands

Allow Traffic

Permit traffic from source to destination.

routerly allow [source] access to [destination] [optional: port/protocol]

Examples:

routerly allow home access to internet
routerly allow guest access to internet
routerly allow office access to servers port 443
routerly allow admin access to all port 22
routerly allow 192.168.1.50 access to 10.0.1.100

Port Specifications:

port 80                    # Single port
port 80,443                # Multiple ports
port 8000-9000             # Port range
protocol tcp               # Protocol only
port 443 protocol tcp      # Port and protocol

Deny Traffic

Block traffic from source to destination.

routerly deny [source] access to [destination]

Examples:

routerly deny guest access to home
routerly deny iot access to internet
routerly deny all access to management port 22

Notes:

Deny rules are processed before allow rules
Be specific to avoid accidentally blocking legitimate traffic

Prioritize Traffic

Give priority to specific traffic types.

routerly prioritize [traffic-type] on [interface]

Examples:

routerly prioritize video traffic on wan
routerly prioritize voip on all interfaces
routerly prioritize port 22 on wan

Traffic Types:

video - Common video streaming ports
voip - Voice over IP protocols
gaming - Common gaming traffic
port X - Specific port number

Limit Traffic

Restrict bandwidth for specific traffic.

routerly limit [source] to [bandwidth] [optional: on interface]

Examples:

routerly limit guest to 10mbps
routerly limit downloads to 50mbps on wan
routerly limit 192.168.2.0/24 to 5mbps

Bandwidth Units: kbps, mbps, gbps

Interface Commands

Set Interface Role

Assign a role to a physical interface.

routerly set [interface] as [role]

Examples:

routerly set eth0 as wan
routerly set eth1 as lan
routerly set eth2 as guest
routerly set wlan0 as management

Roles: wan, lan, guest, dmz, management, trunk

Show Interfaces

List all network interfaces and their roles.

routerly show interfaces

Output:

Interface  Role        Status  IP Address
eth0       wan         up      203.0.113.10
eth1       lan         up      192.168.1.1
eth2       guest       up      192.168.2.1
eth3       dmz         down    -

Status Commands

Show Rules

Display active routing rules.

routerly show rules [optional: for network]

Examples:

routerly show rules
routerly show rules for home
routerly show rules for guest

Output Format:

ID  Source    Destination  Action  Port     Protocol
1   home      internet     allow   any      any
2   guest     internet     allow   any      any
3   guest     home         deny    any      any
4   office    servers      allow   443      tcp

Show Networks

List all defined network aliases.

routerly show networks

Output:

Name        CIDR              Devices
home        192.168.1.0/24    15
guest       192.168.2.0/24    3
office      10.0.1.0/24       42
dmz         10.0.10.0/24      5

Show Status

Display system status and statistics.

routerly show status

Output Includes:

Active rules count
Defined networks
Interface status
Traffic statistics
System uptime
Memory usage

Testing Commands

Test Connection

Simulate traffic to see which rule applies.

routerly test [source] to [destination] [optional: port]

Examples:

routerly test home to internet
routerly test guest to 192.168.1.50
routerly test 192.168.2.10 to 10.0.1.100 port 443

Output:

Source: 192.168.2.10 (guest)
Destination: 10.0.1.100 (office)
Port: 443
Protocol: tcp

Matched Rule: #4 - deny guest access to office
Result: DENIED

Logging Commands

View Logs

Display recent routing events.

routerly logs [optional: filter]

Examples:

routerly logs                  # All events
routerly logs denied           # Only denied traffic
routerly logs allowed          # Only allowed traffic
routerly logs for guest        # Events involving guest network
routerly logs port 22          # Events on port 22

Output Format:

2026-01-14 10:23:15  DENIED   192.168.2.50 → 192.168.1.100  port 445  Rule #3
2026-01-14 10:23:18  ALLOWED  192.168.1.75 → 8.8.8.8        port 53   Rule #1
2026-01-14 10:23:22  DENIED   192.168.2.30 → 192.168.1.1    port 22   Rule #3

Clear Logs

Remove old log entries.

routerly clear logs [optional: older than X days]

Examples:

routerly clear logs
routerly clear logs older than 7 days

Management Commands

Save Configuration

Persist current rules to disk (automatic in most cases).

routerly save

Load Configuration

Reload rules from saved configuration.

routerly load

Reset Configuration

Remove all rules and aliases (requires confirmation).

routerly reset

Warning: This deletes all configuration. Backup first!

Backup Configuration

Export configuration to a file.

routerly backup to [filename]

Example:

routerly backup to /home/admin/routerly-backup-2026-01-14.conf

Restore Configuration

Import configuration from a backup file.

routerly restore from [filename]

Example:

routerly restore from /home/admin/routerly-backup-2026-01-14.conf

System Commands

Update System

Check for and apply system updates.

routerly update

Notes:

Ubuntu Core handles most updates automatically
This command forces an immediate check
System may reboot if kernel updates are applied

Show Version

Display Routerly and system version information.

routerly version

Output:

Routerly: v1.0.0
Ubuntu Core: 22
Kernel: 5.15.0-91-generic
Build: 20260314-1830

Advanced Usage

Rule Priority

Rules are evaluated in order. First match wins.

# This works as expected
routerly deny guest access to admin
routerly allow guest access to internet

# This does NOT work (internet includes admin)
routerly allow guest access to internet
routerly deny guest access to admin  # Never reached!

Best Practice: Deny rules first, then allow rules.

Complex Scenarios

Combine commands to build sophisticated setups:

# Isolated guest network with internet only
routerly define guest as 192.168.2.0/24
routerly deny guest access to local
routerly allow guest access to internet
routerly limit guest to 20mbps

# Office with external SSH but protected web servers
routerly define office as 10.0.1.0/24
routerly allow internet access to office port 22
routerly deny internet access to office port 80
routerly deny internet access to office port 443
routerly allow office access to internet

Getting Help

Built-in Help

routerly help                 # General help
routerly help allow           # Help for specific command
routerly help examples        # Common examples

Online Resources

Full documentation: docs.routerly.dev
GitHub issues: github.com/yourusername/routerly/issues
Community discussions: GitHub Discussions

Troubleshooting Commands

Verify Rule Syntax

Test if a command is valid without applying it.

routerly verify "allow home access to internet"

Show Internal State

View nftables rules (for advanced debugging).

routerly show internal rules

Warning: This shows raw nftables output and is meant for debugging only.

This reference covers v1.0 planned functionality. Report unclear commands or missing features on GitHub.