Skip to main content

MREG CLI Build Status

mreg-cli is a command line interface for the MREG API.

Setup

Options can be set in ~/.config/mreg-cli.conf. A typical config file looks like this:

[mreg]
url=https://mreg.example.com:8000
user=mreg-user

An example config file can be found in data/mreg-cli.conf.

Config options

URL

The URL of the MREG server. This is the only required option.

[mreg]
url=https://mreg.example.com:8000

The URL can also be specified as a command line argument:

mreg-cli --url "https://mreg.example.com:8000"

User

The username to use when connecting to the MREG server. This is optional, and if not specified, the CLI will try to use the current user's username.

[mreg]
user=mreg-user

The user can also be specified as a command line argument:

mreg-cli --user "mreg-user"

Domain

Default domain to use for hostnames. This is optional, and if not specified, the CLI will use uio.no as the default domain.

[mreg]
domain=uio.no

The domain can also be specified as a command line argument:

mreg-cli --domain "uio.no"

Prompt

The prompt text can be configured with a custom format string. The available variables are:

  • {user}: Username of active user
  • {proto}: Protocol part of the server URL
  • {host}: Name part of the server URL
  • {port}: Port part of the server URL (if any)
  • {domain}: Domain name. Defaults to uio.no if not specified.

By default the prompt is set to {user}@{host}, which is equivalent to the following config:

[mreg]
prompt={user}@{host}

Which results in a prompt like this:

admin@mreg.example.com>

Command line

A custom prompt string can be specified as a command line argument as well:

mreg-cli --prompt "<string>"

Disabling the prompt prefix text

The prompt text can be disabled by setting it to no value in the config file or by using the --prompt flag with an empty string.

[mreg]
prompt=
mreg-cli --prompt ""

Which results in the following prompt:

>

Log file

The location of the log file. The default location is $XDG_DATA_DIRS/mreg-cli/mreg-cli.log, which is typically ~/.local/share/mreg-cli/mreg-cli.log.

[mreg]
logfile=/var/log/mreg-cli.log

The log file can also be specified as a command line argument:

mreg-cli --logfile "/var/log/mreg-cli.log"

Timeout

The timeout for HTTP requests to the MREG server. The default is 20 seconds.

[mreg]
timeout=20

Cache

Enable/disable caching of API results. Cache is always cleared on every write request (POST, PUT, PATCH, DELETE).

[mreg]
cache=true

Cache TTL

Time-to-live for cached API results, in seconds. Defaults to 60 seconds (1 minute).

[mreg]
cache_ttl=60

History

Enable/disable command history. Enabled by default.

[mreg]
history=true

History file

Location of the command history file. Defaults to $XDG_DATA_DIRS/mreg-cli/history, which is typically ~/.local/share/mreg-cli/history.

[mreg]
history_file=/path/to/history/file

Category tags

List of valid category tags for networks. Used by network create.

[mreg]
category_tags=default,production,development,test

Location tags

List of valid location tags for networks. Used by network create.

[mreg]
location_tags=default,oslo,bergen,stavanger

General usage

Commands in mreg-cli take on the form of a fairly standard command line interface:

host add myhost.example.com -ip 192.168.1.1 -contact me@example.com -comment "My host"

Here we are using the host add command to add a new host. The command takes the hostname as a positional argument, while IP address, contact, and comment are specified with flags. Multiple contacts can be added by repeating -contact.

Filtering

mreg-cli support output filtering via the operators | and |!. The | operator is used to filter the output to only show the lines matching the text specified after the operator. Using |! will show the lines not matching the text specified after the operator. The filter text is a standard python regular expression. Some examples:

mreg> host info one.example.com
Name:         one.example.com
Contact:      me@example.com
A_Records     IP                           MAC
              192.168.1.2                  aa:bb:cc:dd:ee:ff
TTL:          (Default)
TXT:          v=spf1 -all
mreg> host info one.example.com | example
Name:         one.example.com
Contact:      me@example.com
mreg> host info one.example.com | me.*com
Contact:      me@example.com
mreg> host info one.example.com |! me.*com
Name:         one.example.com
A_Records     IP                           MAC
              192.168.1.2                  aa:bb:cc:dd:ee:ff
TTL:          (Default)
TXT:          v=spf1 -all

Forcing commands

A number of commands take a -force flag. This flag is typically required when the operation will fail internal validation. However, please note that -force is emphatically not a "I know what I'm doing" flag. It is a "I know what I'm doing and I'm willing to take responsibility for the consequences" flag. If you're not sure what you're doing, don't use -force.

As an example, you may add a host to a network unknown to mreg, or a frozen network. You may want to assiciate a mac address to a host or an IP that already has a mac address associated with it. All of these examples will cause a validation failure, but you may bypass this failure by using -force. This is fine if you for example are certain the new mac address is supposed to replace the old one, but if you mistakenly associate a mac address to the wrong host, you may cause the host to be unreachable on the network. -force exists to alert you that you are doing something that may have unintended consequences, and you should be sure you know what you are doing before using it.

Command set

Host

   host add <name> [-ip <ip/net>] [-contact <contact>]... [-comment <comment>]
       Add a new host with the given name, optional ip or subnet, contact(s), and comment.

!!!note Force is required when adding a host with an ip in a subnet not controlled by MREG or in a frozen subnet.

   host remove <name|ip>
       Remove host. If <name> is an alias the cname host is removed.
       
   host info <name|ip>
       Print information about host. If <name> is an alias the cname hosts info is shown.
       
   host rename <old-name> <new-name>
       Rename host. If <old-name> is an alias then the alias is renamed.
    
   host set_comment <name> <comment>
       Set comment for host. If <name> is an alias the cname host is updated.
       
   host set_contact <name> <contact>
       Set contact for host. If <name> is an alias the cname host is updated.

A/AAAA

The API doesn't differentiate between ipv4 and ipv6, so A/AAAA are only different on the client side.
Require force if the host already has A/AAAA record(s), or if the ip is in a subnet not controlled by MREG.

   host a_add <name> <ip|subnet>
       Add an A record to host. If <name> is an alias the cname host is used.
       
   host a_change <name> <old-ip> <new-ip-or-subnet>
       Change A record. If <name> is an alias the cname host is used.
       
   host a_remove <name> <ip>
       Remove A record from host. If <name> is an alias the cname host is used.
       
   host a_show <name>
       Show hosts ipaddresses. If <name> is an alias the cname host is used.
       
   host aaaa_add <name> <ipv6>
       Add an AAAA record to host. If <name> is an alias the cname host is used.
       
   host aaaa_change <name> <old-ipv6> <new-ipv6>
       Change AAAA record. If <name> is an alias the cname host is used.
       
   host aaaa_remove <name> <ipv6>
       Remove AAAA record from host. If <name> is an alias the cname host is used.
       
   host aaaa_show <name>
       Show hosts ipaddresses. If <name> is an alias the cname host is used.

CNAME

   host cname_add <existing-name> <new-alias>
       Add a CNAME record to host. If <existing-name> is an alias the cname host is used as
       target for <new-alias>.
       
   host cname_remove <name> <alias-to-delete>
       Remove CNAME record.
       
   host cname_show <name>
       Show CNAME records for host. If <name> is an alias the cname hosts aliases are shown.

HINFO

   host hinfo_remove <name>
       Remove hinfo for host. If <name> is an alias the cname host is updated.
       
   host hinfo_set <name> <hinfo>
       Set hinfo for host. If <name> is an alias the cname host is updated.
       
   host hinfo_show <name>
       Show hinfo for host. If <name> is an alias the cname hosts hinfo is shown.

LOC

All LOC commands require force.

   host loc_remove <name>
       Remove location from host. If <name> is an alias the cname host is updated.
       
   host loc_set <name> <loc>
       Set location of host. If <name> is an alias the cname host is updated.
       
   host loc_show <name>
       Show location of host. If <name> is an alias the cname hosts LOC is shown.

NAPTR

   host naptr_add <name> <preference> <order> <flagg> <service> <regexp> <replacement>
       Add a NAPTR record to host.
       
   host naptr_remove <name> <replacement>
       Remove NAPTR record.
       
   host naptr_show <name>
       Show all NAPTR records for host.

PTR

   host ptr_change <ipv4|ipv6> <old-name> <new-name>
       Move PTR record from <old-name> to <new-name>.
       
   host ptr_remove <ipv4|ipv6> <name>
       Remove PTR record from host.
       
   host ptr_set <ipv4|ipv6> <name>
       Create a PTR record for host.
       
   host ptr_show <ipv4|ipv6>
       Show PTR record matching given ip (empty input shows all PTR records).

SRV

Require force if a host with target-name doesn't exist.

   host srv_add <service-name> <pri> <weight> <port> <target-name>
       Add SRV record.
       
   host srv_remove <service-name>
       Remove SRV record.
       
   host srv_show <service-name>
       Show SRV records for the service.

SSHFP

   host sshfp_add <name> <algorithm> <hash_type> <fingerprint>
       Add SSHFP record for the host.

   host sshfp_remove <name> <fingerprint>
       Remove SSHFP record with a given fingerprint from the host.
       A missing fingerprint removes all SSHFP records for the host.

   host sshfp_show <name>
       Show SSHFP records for the host.

TTL

   host ttl_remove <name>
       Remove explicit TTL for host. If <name> is an alias the alias host is updated.
       
   host ttl_set <name> <ttl>
       Set ttl for host. Valid values are 300 <= TTL <= 68400 or "default". If <name> is an
       alias the alias host is updated.
       
   host ttl_show <name>
       Show ttl for host. If <name> is an alias the alias hosts TTL is shown.

TXT

   host txt_add <name> <text>
       Add a txt record to host. <text> must be enclosed in double quotes if it contains more
       than one word.
       
   host txt_remove <name> <text>
       Remove TXT record for host matching <text>.
       
   host txt_show <name>
       Show all TXT records for host.

DHCP

   dhcp assoc <name|ip> <mac-addr>
       Associate MAC address with host. If host got multiple A/AAAA records an IP must be
       given instead of name.
       
   dhcp disassoc <name|ip>
       Disassociate MAC address with host/ip. If host got multiple A/AAAA records an IP must be
       given instead of name

subnet

   subnet create <subnet> <description> <vlan> <dns_delegated> <category> <location> <frozen>
       Create a new subnet
       
   subnet import <file>
       Import subnet data from <file>.
       
   subnet info <subnet>
       Display subnet info
       
   subnet list_unused_addresses <subnet>
       Lists all the unused addresses for a subnet
       
   subnet list_used_addresses <subnet>
       Lists all the used addresses for a subnet
       
   subnet remove <subnet>
       Remove subnet
       
   subnet set_category <subnet> <category_tag>
       Set category tag for subnet
       
   subnet set_description <subnet> <description>
       Set description for subnet
       
   subnet set_dns_delegated <subnet>
       Set that DNS-administration is being handled elsewhere.
       
   subnet set_frozen <subnet>
       Freeze a subnet.
       
   subnet set_location <subnet> <location_tag>
       Set location tag for subnet
       
   subnet set_reserved <subnet> <number>
       Set number of reserved hosts.
       
   subnet set_vlan <subnet> <vlan>
       Set VLAN for subnet
       
   subnet unset_dns_delegated <subnet>
       Set that DNS-administration is not being handled elsewhere.
       
   subnet unset_frozen <subnet>
       Unfreeze a subnet.

zone

   zone create <zone-name> (<nameservers>)
       Create new zone.
       
   zone delete <zone-name>
       Delete a zone
       
   zone set_ns <zone-name> (<nameservers>)
       Update nameservers for an existing zone.
       
   zone set_soa <zone-name> (<primary_ns> <email> <serialno> <refresh> <retry> <expire> <ttl>)
       Updated the SOA of a zone.

other

The CLI also provides these miscellaneous functions:

List available commands without a argument, or display detailed help for a command or for a specific option of a command.

help
help <cmd>
<cmd> help <option>

shell <cmd>: Run a bash command.

source <file-name> [--exit]: Read commands from a file. If --exit is supplied then it'll stop executing on error.

Metadata

Release files for mreg-cli 1.13.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mreg-cli 1.13.0
File Size Uploaded Provenance Actions
mreg_cli-1.13.0.tar.gz 254.0 kB With provenance Details for mreg_cli-1.13.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mreg-cli 1.13.0
File Interpreter ABI Platform Actions
mreg_cli-1.13.0-py3-none-any.whl Python 3 none any Details for mreg_cli-1.13.0-py3-none-any.whl

Total release size: 375.6 kB

Release files / mreg_cli-1.13.0.tar.gz

Download URL mreg_cli-1.13.0.tar.gz
Size 254.0 kB
Tags Source
SHA-256 checksum
How to use checksums
e46a99c9debcc3bbf2e050f4112d0cbcb30fc198a1a2bde0f1bb40f8000d7830
BLAKE2b-256 checksum
How to use checksums
9a01a3af1f5da4539da74e25af39c2d160f09430c1c4f90d54ea64e5a3da7059
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Release files / mreg_cli-1.13.0-py3-none-any.whl

Download URL mreg_cli-1.13.0-py3-none-any.whl
Size 121.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dbd5b8fcf3b63bdb815094d88e2ac1f89757351e364b0554c0be1c4a1fcfc61b
BLAKE2b-256 checksum
How to use checksums
7c7aa4134b8b9be12f281a4122d0e5f5a91d2743e08b53e21c6059fb79a4fc20
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Security for mreg-cli 1.13.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mreg_cli-1.13.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.13.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page