starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-11 20:00:28 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

[Feature] Add expiration and status filtering support to nodes CLI command #1056

New Issue
Closed
opened 2025-12-29 02:27:59 +01:00 by adam · 1 comment
adam commented 2025-12-29 02:27:59 +01:00
Owner
Copy Link

Originally created by @dmeremyanin on GitHub (Jun 28, 2025).

Use case

The headscale nodes CLI command currently supports filtering by user, which is super helpful. However, there's no built-in way to filter nodes by status, such as whether they are expired or online.

In our case, we use a script to regularly check for online nodes, and typically only 5–10 out of 100+ nodes are active at any given time. Being able to apply filters at the CLI level would reduce unnecessary output and also lessen the load on the Headscale server, especially in larger deployments.

Description

I propose adding two optional flags to the headscale nodes list command:

  • --expired=<true|false> – filter nodes based on expiration:

    # List only expired nodes
headscale nodes list --expired=true

# List only non-expired (active) nodes
headscale nodes list --expired=false

  • --online=<true|false> – filter nodes based on online status:

    # List only online nodes
headscale nodes list --online=true

# List only offline nodes
headscale nodes list --online=false

These filters should be combinable with existing options:

headscale nodes list --user=username --expired=true online=false # list expired, offline nodes for a specific user

If neither flag is provided, the command behavior remains unchanged – returning all nodes.

Contribution

  • I can write the design doc for this feature
  • I can contribute this feature

How can it be implemented?

Add two new flags to the listNodesCmd – online and expired. The expiration filter can be implemented using SQL. The online filter can be evaluated only in runtime, as the online status is not persisted in the database.

I'd be happy to help with a PR if this feature request is accepted.

Originally created by @dmeremyanin on GitHub (Jun 28, 2025). ### Use case The headscale nodes CLI command currently supports filtering by user, which is super helpful. However, there's no built-in way to filter nodes by status, such as whether they are expired or online. In our case, we use a script to regularly check for online nodes, and typically only 5–10 out of 100+ nodes are active at any given time. Being able to apply filters at the CLI level would reduce unnecessary output and also lessen the load on the Headscale server, especially in larger deployments. ### Description I propose adding two **optional** flags to the `headscale nodes list` command: * `--expired=<true|false>` – filter nodes based on expiration: ``` # List only expired nodes headscale nodes list --expired=true # List only non-expired (active) nodes headscale nodes list --expired=false ``` * `--online=<true|false>` – filter nodes based on online status: ``` # List only online nodes headscale nodes list --online=true # List only offline nodes headscale nodes list --online=false ``` These filters should be combinable with existing options: ```bash headscale nodes list --user=username --expired=true online=false # list expired, offline nodes for a specific user ``` If neither flag is provided, the command behavior remains unchanged – returning all nodes. ### Contribution - [x] I can write the design doc for this feature - [x] I can contribute this feature ### How can it be implemented? Add two new flags to the `listNodesCmd` – `online` and `expired`. The expiration filter can be implemented using SQL. The online filter can be evaluated only in runtime, as the online status is not persisted in the database. I'd be happy to help with a PR if this feature request is accepted.
adam added the enhancementstale labels 2025-12-29 02:27:59 +01:00
adam closed this issue 2025-12-29 02:27:59 +01:00
adam commented 2025-12-29 02:27:59 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Sep 27, 2025):

This issue is stale because it has been open for 90 days with no activity.

@github-actions[bot] commented on GitHub (Sep 27, 2025): This issue is stale because it has been open for 90 days with no activity.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CLI
DERP
DNS
Nix
OIDC
SSH
bug
database
documentation
duplicate
enhancement
faq
good first issue
grants
help wanted
might-come
needs design doc
needs investigation
no-stale-bot
out of scope
performance
policy 📝
pull-request
Mirrored from GitHub Pull Request
 question
regression
routes
stale
tags
tailscale-feature-gap
well described ❤️
wontfix
No Label enhancement stale
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/headscale#1056
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?