dirless-cli import loads a JSON file produced by
dirless-cli export back into your
directory. Together the two commands close the loop: export is your backup,
import is your restore - and if you ever left, it is also the way back in.
On any enrolled host, export your portal-managed local users to a JSON file.
Requires dirless-cli 0.6.0 or newer.
dirless-cli export --source local --out backup.json--source local for backups. The import
target is the local (portal-managed) side of your directory. A default
merged export also contains your cloud-synced users, and
importing those would turn them into local users that shadow the IdP-synced
originals. The importer warns you when it sees UIDs below 100000, which is
the tell-tale sign of cloud users in the file.
Cloud-synced users do not need backing up: they re-sync from AWS IAM Identity Center automatically. The local snapshot is the part only you have - which is exactly why it is the part worth a backup.
Preview what would be imported. A dry run parses and validates the file but never contacts the backend.
dirless-cli import --json backup.json --dry-runParsed Dirless export:
Users : 3
Groups : 2
alice uid=100001 gid=100000 /bin/zsh (2 ssh keys)
bob uid=100002 gid=100000 /bin/bash
carol uid=100003 gid=100000 /bin/bash (1 ssh key)
%dirless-local gid=100000 members=[alice, bob, carol]
%devs gid=100010 members=[alice, bob]
Run the same command without --dry-run. The importer fetches
your current local snapshot, merges the file in, encrypts the result to
your age key locally, and pushes it back - the server only ever sees an
encrypted blob.
dirless-cli import --json backup.jsonFetching existing local snapshot from https://acme.dirless.com...
found 2 existing local user(s)
Pushing 3 local user(s), 2 group(s)...
✓ Import complete.
Imported : 1 user(s)
Total : 3 local user(s), 2 group(s)
Enrolled hosts will pick the users up on their next agent sync (~60s).
Users that already exist in your directory are never touched: they are
skipped with a note, so importing a backup is safe and idempotent - if
nothing is missing, nothing changes. To make the file win instead (a
true point-in-time restore), pass --overwrite-existing:
dirless-cli import --json backup.json --overwrite-existing
Group memberships from the file are merged with existing groups, and the
dirless-local catch-all group is rebuilt automatically to
hold every local user.
Within one sync cycle (60 seconds by default) every enrolled host sees the restored users:
getent passwd carol
carol:x:100003:100000:Carol Chen:/home/carol:/bin/bash
dirless-cli list-usersThe users also appear in the portal under Directory → Local users, SSH keys included.
| Flag | Effect |
|---|---|
--json FILE |
JSON export from dirless-cli export (required) |
--dry-run |
Parse and report only - never contacts the backend |
--overwrite-existing |
Replace local users that already exist (default: skip them) |
--config PATH |
Agent config file (default: /etc/dirless/dirless-agent.toml) |
--server / --token / --tenant-id / --age-key |
Run from a non-enrolled machine by passing the backend URL, bearer token, tenant ID, and age private key explicitly |
dirless-cli import-freeipa,
which shares the same merge engine and flags.