Migrating to v7
Atlas 7 keeps the v6 storage format. Backups written by v6 stay readable, incremental runs continue where they left off, and no fresh backup is needed. For most installations the only change is that the CLI keeps Microsoft Entra credentials in named tenant profiles.
npm install -g @wisecom/atlas-cli@7
atlas tenants list # existing credentials appear as the "default" profile
atlas tenants validate # Graph token check for the selected profile
atlas config validate # S3 checkWho is affected
| You use | What to do |
|---|---|
| The CLI with one tenant | Nothing required. Existing credentials load as the default profile |
Scheduled jobs that branch on the exit code, export with save, or run without a terminal | Review Changes that affect scheduled jobs |
Scripts that run atlas config set, get, list, or unset on the Graph credentials, or rely on atlas config validate to check Graph | Switch to atlas tenants. See What breaks |
One host backing up several tenants by swapping ATLAS_* variables | Move each tenant into a profile |
atlas replicate or atlas rehydrate | Set up replication at the storage provider. See Replication moves to the storage provider |
| The SDK with TypeScript | Update code for the SDK changes and rerun your type checker |
| Contacts, Calendar, or Teams | New and opt-in. Grant their permissions first |
What changed
| Area | v6 | v7 |
|---|---|---|
| Microsoft Entra credentials (CLI) | One set, atlas config set tenant.id, client.id, client.secret | Named tenant profiles, managed with atlas tenants. Existing credentials load as default |
atlas config | Every key. validate checks Graph and S3 | Shared S3 and passphrase keys only. validate checks S3 |
| Selecting a tenant | Swap ATLAS_TENANT_ID, ATLAS_CLIENT_ID, ATLAS_CLIENT_SECRET | --profile <name>, ATLAS_PROFILE, or atlas tenants use |
| Cross-tenant restore | Manual credential swap | --target-profile on the CLI, createTenant and targetTenant in the SDK |
| Workloads | Outlook, OneDrive, SharePoint | Adds Contacts, Calendar, and Teams channel messages |
| Storage format | v6 paths | Unchanged. Contacts, Calendar, and Teams add the contacts/, calendar/, and teams/ prefixes |
| Replication | atlas replicate, atlas rehydrate, SDK replication methods | Removed. The storage provider makes the replica, and Atlas restores from and verifies it |
| Passphrase rotation | atlas keys rewrap re-wraps one tenant | atlas keys rewrap re-wraps every profile, see below |
| Snapshot deletion | Any snapshot | Only the newest snapshot of a mailbox, owner, or site. Others exit 11 |
| Concurrent operations on one owner | Not detected | Refused with ATLAS_OWNER_BUSY, exit 12 |
| Rejected Graph credentials | Exit 1 | Exit 4, ATLAS_AUTH_DENIED |
Graph Retry-After above 5 minutes | Failed after one attempt | Waited out, up to 1 hour |
| Restore fidelity | Messages restored unflagged, folder colours not kept | Restores the follow-up flag and the pin. Captures OneDrive and SharePoint folder colours |
In v7, atlas keys rewrap re-wraps the data key of every profile, stores the new passphrase only when every tenant is done, and exits 2 when one is left. atlas keys purge-old-wrappers deletes the old wrapper versions. See Rotation procedure.
CLI credentials move into tenant profiles
A tenant profile is one app registration: tenant ID, client ID, and client secret. S3 settings and the encryption passphrase stay shared across profiles. See Configuration for the stored layout and selection order.
What keeps working
- The encrypted store. Top-level
tenant_id,client_id, andclient_secretfrom v6 load as thedefaultprofile. The firstatlas tenantswrite moves them intotenants.defaultin the store. atlas.config.json. Top-level Graph fields in the file are read asdefaulttoo. Atlas never rewrites the file.ATLAS_*environment variables.ATLAS_TENANT_ID,ATLAS_CLIENT_ID, andATLAS_CLIENT_SECRETstill work and override the selected profile. A CI job or container that sets all three and stores no profile runs unchanged, with no new output.-t, --tenant. It still overrides the tenant whose bucket a command reads. Without it, the selected profile's tenant ID names the bucket,atlas-<tenant-id>.
What breaks
Scripts that manage the Graph credentials through atlas config fail with a message that points to atlas tenants add. Replace them:
| v6 | v7 |
|---|---|
atlas config set tenant.id <id> | atlas tenants add <name> --tenant-id <id> --client-id <id> --client-secret - |
atlas config set client.secret - (rotation) | atlas tenants add <name> --tenant-id <id> --client-id <id> --client-secret - --replace |
atlas config get client.id, atlas config list | atlas tenants list |
atlas config unset client.secret | atlas tenants remove <name> |
atlas config validate (Graph part) | atlas tenants validate [name], or --all |
atlas tenants add takes all three values at once, so a secret rotation passes the tenant and client IDs again with --replace. It checks the formats before writing, then requests a Graph token. If the token request fails, the profile is kept and the command exits 1.
Naming the existing profile
default works as a name. To give the existing credentials a real one, add them under the new name, make it active, then remove default:
atlas tenants add contoso --tenant-id <tenant-id> --client-id <client-id> --client-secret -
atlas tenants use contoso
atlas tenants remove defaultremove deletes only profiles held in the encrypted store. If default comes from top-level fields in atlas.config.json, delete those fields from the file instead.
Several tenants on one host
Add a profile per tenant and select one per run:
atlas tenants add fabrikam --tenant-id <tenant-id> --client-id <client-id> --client-secret -
atlas --profile fabrikam outlook backup -m user@example.comScheduled jobs set ATLAS_PROFILE or pass --profile, so an interactive atlas tenants use on the same account cannot change which tenant and bucket the next scheduled run uses.
Environment variables override every selected profile
A shell or unit that still exports ATLAS_TENANT_ID, ATLAS_CLIENT_ID, or ATLAS_CLIENT_SECRET applies them to whichever profile a command selects. Remove them from systemd units, cron environments, and .env files once the credentials live in profiles.
Atlas warns on stderr, naming the variables and the profile, whenever they replace a profile value. When only some are set and they change the tenant ID or client ID, the run is refused with exit code 6, because it would combine one tenant's ID with another tenant's secret. See Configuration.
All profiles share one S3 key and one passphrase, so that key reaches every profile's bucket. When tenants must be isolated at the storage layer, keep a separate installation per tenant. See Bucket isolation.
Cross-tenant restore replaces the credential swap
In v6 you restored into another tenant by exporting the destination's credentials and passing the source tenant with -t. That still runs, but v7 has an explicit form:
atlas --profile contoso outlook restore -s <snapshot-id> --target-profile fabrikam -T user@example.comThe source profile reads and decrypts the backup, and the target profile writes. An explicit target (-T here) is required, because object IDs differ between tenants. Under a manual swap, v7 keeps the source tenant's identity registry read-only, because Microsoft Graph answers for the other tenant. See Cross-tenant restore and Graph credentials belong to another tenant.
New workloads and their permissions
Contacts, Calendar, and Teams are opt-in. An app registration granted for v6 keeps backing up Outlook, OneDrive, and SharePoint without changes. Grant these only for the workloads you add:
| Workload | Backup permissions | Restore |
|---|---|---|
| Contacts | Contacts.Read | Contacts.ReadWrite |
| Calendar | Calendars.Read | Calendars.ReadWrite |
| Teams | Eight Application permissions, including the protected ChannelMessage.Read.All. See Teams application permissions | Export only, through atlas teams save |
Request Teams access early
ChannelMessage.Read.All can need Microsoft's approval before Microsoft Graph returns channel messages, even after admin consent. Request it before you schedule Teams backups.
Replication moves to the storage provider
# v6: Atlas copied snapshots to a second endpoint
atlas replicate -m user@example.com --target-config ./offsite.json
# v7: the provider replicates the bucket; Atlas reads the replica when you point it there
ATLAS_S3_ENDPOINT=https://replica.example.com atlas outlook verify -m user@example.com -s <snapshot-id> --fastStorage providers replicate buckets natively and continuously. AWS S3 replication, MinIO replication, and Backblaze B2 Cloud Replication carry object versions and Object Lock retention and need no Atlas run or schedule. A re-wrapped data key reaches the replica on its own, as a new version of _meta/dek.enc, which atlas replicate never did after atlas keys rewrap. Atlas's job toward a replica is to restore from it and verify it.
What is removed
atlas replicateandatlas rehydrate.- The 13 SDK methods:
replicateSnapshot,replicateMailbox,rehydrateSnapshot,rehydrateMailbox,rehydrateTenant,getReplicationStatus, andgetReplicationStatusByOwneron the instance;replicateSnapshot,replicateAll,rehydrateSnapshot, andrehydrateOwneronatlas.onedrive;replicateSnapshot,replicateAll,rehydrateSnapshot, andrehydrateSiteonatlas.sharepoint. createStorageTarget,StorageTarget,StorageTargetConfig, and thetargetfield of storage request events.- The
--target-*options ofatlas stats storageand thetargetoption ofgetStorageUsage, which no v6 release shipped. Measure a replica by pointing the S3 endpoint at it. - The result and option types
OneDriveSdkReplicationResult,SharePointSdkReplicationResult, andRehydrationWorkload.
What to do
- Set up provider replication, or a scheduled
rclone copyormc mirrorto another provider. See Replica setup. - Remove the
atlas replicatecron jobs and systemd timers. - To restore or verify from the replica, point
ATLAS_S3_ENDPOINTand the keys at it. See Replicas. - AWS S3 and Backblaze B2 replicas have a different bucket name. Name it with
ATLAS_S3_BUCKET, a tenant profile's--bucket, or the SDK'ss3Bucket. See Bucket override.
Never use a deleting sync for the replica
rclone sync and mc mirror --remove delete objects on the replica when they are missing from the source. Use rclone copy or mc mirror without --remove.
What happens to existing data
Replicas written by v6 keep the bucket name atlas-<tenant-id> on their own endpoint and are directly usable. The _meta/replication/ status records in the primary bucket and _meta/replica.marker in each replica are inert: atlas stats storage still counts them, and a tenant purge deletes them. See Legacy Atlas 6 objects to remove them sooner.
Changes that affect scheduled jobs
Atlas 7 reports several situations that v6 passed over in silence. A job that exited 0 on v6 can exit nonzero on v7 without anything new being wrong. Review scripts that branch on the exit code or run without a terminal.
Exit codes
The numbers 0 to 9 keep their meaning. Some now cover more cases, and two are new:
| Code | What v7 adds |
|---|---|
1 | A confirmation prompt that gets no answer, and ATLAS_WRITE_REFUSED. No longer covers rejected Graph credentials, which move to 4 |
2 | A OneDrive or SharePoint backup that ends UNHEALTHY, including a run with no new error where a file is still on the list of failed files. A --folder or --file-filter value that matched nothing while other values matched. A keys rewrap or keys purge-old-wrappers that left a tenant unfinished |
3 | A Microsoft Graph outage is now named ATLAS_GRAPH_UNAVAILABLE. A token request that Microsoft Entra ID leaves unanswered, or answers with 408, 429, a 5xx, or temporarily_unavailable, is retried and ends here too |
4 | A token request that Microsoft Entra ID refuses: a wrong or expired client secret, an unknown client ID, or a tenant that does not exist. v6 exited 1. Also ATLAS_ACCESS_REFUSED, and a status command that Microsoft Graph refuses with 401 or 403 |
7 | A --folder, --file-filter, or --message selection that matched nothing at all |
9 | ATLAS_FORMAT_UNSUPPORTED, and a command that skipped a damaged snapshot manifest or version index and named it |
11 | New: ATLAS_SNAPSHOT_NOT_NEWEST |
12 | New: ATLAS_OWNER_BUSY |
The exit code reference has the full table, and Retries and fail-safes says which codes a rerun can fix.
Command behaviour
| Situation | v6 | v7 |
|---|---|---|
save to an output file that exists | Overwrote it | Asks Overwrite? [Y/n]. Pass -y in a job that writes to a fixed path |
| A confirmation prompt with no terminal attached | Depended on the command | Exits 1 and changes nothing. Pass -y in scheduled jobs |
| A selector that matches nothing | Ran and reported success | Fails with exit 7, or 2 when only some values matched |
--message together with -m on atlas outlook restore or save | Acted on the whole mailbox | Refused. Name the snapshot with -s |
delete -s on the newest snapshot | Left the sync checkpoint in place | Removes it too, so the next backup reads the mailbox, drive, or site in full |
| A tenant ID that cannot name an S3 bucket | Failed at the storage provider | Refused with exit 6. Tenant IDs are stored in lowercase |
| A second Ctrl+C | Waited for the run to wind down | Exits at once with status 130 and no final report |
Microsoft Graph sends Retry-After above 5 minutes | Failed the call after one attempt | Waits it out, up to 1 hour, so a throttled run can take longer. A longer value fails with ATLAS_THROTTLED, exit 3. Leave room in job timeouts |
A purge or keys rewrap while a backup runs in the same tenant | Ran alongside it | Refused with exit 12, and the other way round |
| Commands that only read a backup | Opened the tenant for writing | Open it read-only, so restore and verify work with read-only S3 credentials. Protection against concurrent runs is off for such a restore, and Atlas says so |
Storage backend
Atlas 7 depends on conditional writes for the one-operation-per-owner guard, the data key, and snapshot manifests. atlas storage-check gains a Conditional writes row that tests the backend:
atlas storage-checkA backend that ignores conditional writes still stores backups, but it cannot keep two runs on the same mailbox, owner, site, or team apart. See Storage.
A configured bucket override belongs to exactly one tenant. Atlas refuses to open a bucket that already holds another tenant's data. See Bucket override.
Restore fidelity
| Item | v6 | v7 |
|---|---|---|
| Outlook follow-up flag and pin | Restored unflagged and unpinned | Recorded at backup and restored. Messages backed up by v6 still restore unflagged and unpinned |
| OneDrive and SharePoint folder colours | Not captured | Captured on folder entries and shown by list-permissions and restore output. Not reapplied on restore |
| OneDrive and SharePoint sharing | Not captured | Captured, shown by list-permissions, and restored with --restore-permissions |
Outlook folder names on restore and save | Read from the source mailbox, so a departed user's mailbox or a cross-tenant restore failed with 404 | Read from the snapshot. The source mailbox is listed only for folders no manifest records |
First OneDrive and SharePoint backup after upgrading
Atlas 7 captures the sharing on files and folders. Sync checkpoints saved by v6 do not mark which items are shared, so the first v7 backup lists each drive and library in full once. Unchanged files are not downloaded again, but the run reads the permissions of every shared item and takes longer than an incremental backup. See First backup after upgrading and the cost of capturing sharing.
New commands and options
| Command | Purpose |
|---|---|
atlas tenants add, list, use, remove, validate | Manage tenant profiles |
--profile, --target-profile | Select the tenant for a run, and the destination tenant of a restore |
atlas contacts, atlas calendar, atlas teams | The new workloads |
atlas <workload> quarantine --key <key> | Move a damaged manifest or index aside after an exit 9. See Damaged manifests and version indexes |
atlas keys purge-old-wrappers | Delete the data key wrappers an earlier passphrase left behind |
atlas outlook restore --destination <path> | Restore mail under a folder you choose |
atlas onedrive list-permissions, atlas sharepoint list-permissions | Show who had access to which file or folder at a snapshot |
--restore-permissions on atlas onedrive restore and atlas sharepoint restore | Reapply captured sharing. Off by default |
atlas tenants add --bucket <name> | Name a bucket other than atlas-<tenant-id> |
SDK changes
createAtlasInstance still takes every setting explicitly and reads no config file, so tenant profiles do not affect SDK hosts. Most changes are additions. The removals, new members, and new error codes can break a TypeScript build.
| Change | Update your code |
|---|---|
AtlasInstance gains contacts, calendar, teams, and keys | Add them to any hand-written object or mock typed as AtlasInstance. keys.rewrapTenantKeys and keys.purgeOldWrappers cover several tenants that share one passphrase. See Re-wrapping several tenants |
Replication methods, createStorageTarget, and StorageTarget removed | Remove the calls and imports. See What is removed |
StorageRequestEvent loses target | Every event comes from the instance's own bucket. Label events by instance instead |
Each workload API gains quarantine(storageKey), and every workload but Teams gains listSnapshotSummaries | Add them to hand-written mocks of OutlookApi, OneDriveApi, SharePointApi, ContactsApi, or CalendarApi. See Snapshot summaries |
Six new AtlasErrorCode values | Add cases to an exhaustive switch over err.code. See the table below |
MissingGraphPermissionsError is an AuthError, and exported | instanceof AuthError now matches a missing drive grant. See below |
SharePoint sites gain kind | listSites() and resolveSite() return kind: 'site' | 'file_storage_container'. Add it to a hand-written SharePointSdkSite mock. isFileStorageContainerSite(webUrl) is new. See SharePoint Embedded containers |
checkStorage() gains conditionalWrites | Always present. Add it to a hand-written StorageCheckResult mock |
Restore options gain targetTenant | A wrapper that copies restore options field by field drops it until updated |
createTenant, AtlasTenant, AtlasTenantConfig | New. See Cross-tenant restore |
teamsPacingShare on AtlasInstanceConfig | New, optional. Set 1 / n when n processes back up teams of one tenant |
s3Bucket on AtlasInstanceConfig | New, optional. Names a bucket other than atlas-{tenantId}, such as an AWS S3 or B2 replica. See Bucket override |
New error codes
| Code | Error class | Raised when | CLI exit |
|---|---|---|---|
ATLAS_FORMAT_UNSUPPORTED | UnsupportedFormatVersionError, not exported: match on code | Stored data was written by a newer Atlas format version. It is intact: upgrade Atlas | 9 |
ATLAS_WRITE_REFUSED | RefusedWriteError | A backup built a snapshot, index, or sync checkpoint that fails Atlas's own read checks. Nothing is stored | 1 |
ATLAS_SNAPSHOT_NOT_NEWEST | SnapshotNotNewestError | deleteSnapshot or delete -s targets a snapshot that is not the newest of its mailbox, owner, or site | 11 |
ATLAS_OWNER_BUSY | OwnerBusyError | Another operation already runs on the same mailbox, drive owner, site, or team | 12 |
ATLAS_GRAPH_UNAVAILABLE | GraphUnavailableError | Microsoft Graph kept answering 500, 502, 503, or 504, or kept failing on the network, through all 12 retries | 3 |
ATLAS_ACCESS_REFUSED | GraphAccessRefusedError | Microsoft Graph refuses a OneDrive or SharePoint site, drive, or owner with a 403 that is not a missing tenant grant | 4 |
What each change means for existing code:
- Write checks. Snapshot manifests and indexes are written create-only and read back, so a backup can also reject with
StoredObjectConflictErroror aStorageErrornaming the object. Both carryATLAS_STORAGE_FAILURE. The CLI exits1for all three. See Refused and unconfirmed metadata writes. - Snapshot deletion.
outlook.deleteSnapshot,onedrive.deleteSnapshot, andsharepoint.deleteSnapshot, and theirdelete -scommands, refuse any snapshot but the newest. The OneDrive and SharePoint calls now decrypt the manifests to check the order, so they need the tenant's data key. - One operation per owner. Every backup, restore, deletion, and quarantine now holds a lease on its mailbox, drive owner, site, or team, and
purgeTenantDataand the key re-wrap hold one on the whole tenant. Running two operations on one owner at once was never supported. It used to silently overwrite a sync checkpoint and now fails withOwnerBusyError. See Concurrent operations. - Graph outages. A persistent Graph failure used to reject with the raw Graph error, often with an empty
messageand nocodeanAtlasErrorcheck could see.GraphUnavailableErrorcarries that error ascause. Treat it as transient. The CLI exits3as before. See Graph failures. - Refused access. A OneDrive or SharePoint 403 during listing used to reject with
MissingGraphPermissionsError, then a plainErrorwith nocode, whatever the cause. A refusal that Atlas does not attribute to a missing tenant grant, such as a SharePoint Embedded container, now rejects withGraphAccessRefusedError. Retrying returns the same answer: a container is unsupported, and another site may need a per-site grant. It is not anAuthError. - Rejected credentials. A Graph token request that Microsoft Entra ID refuses used to reject with a
GraphErrorwhosestatusCodewas-1. It now rejects with anAuthError,ATLAS_AUTH_DENIED, carrying Entra's answer ascause. A token request that gets no answer or a transient one rejects withGraphUnavailableError. See Graph failures. - Missing permissions.
MissingGraphPermissionsErrorcarriesATLAS_AUTH_DENIEDand the fieldspermissions,status_code, andgraph_code. Its message changed: it names the HTTP status and Graph code, and for SharePoint namesSites.Read.Allor aSites.Selectedgrant on the site. - Storage check probe.
checkStorage()now writes and removes one probe object under_meta/storage-check/, and reportsnot_probedwhen it may not.
What you must do
Storage is unchanged, so hosts that share a bucket can be upgraded one at a time. While any host is still on v6:
- Run Contacts, Calendar, and Teams only from v7 hosts.
- Keep scheduling one operation per mailbox, owner, site, or team. The owner lease only keeps apart hosts that take it.
Upgrade
@wisecom/atlas-clior@wisecom/atlas-sdkto v7.Check the credentials. Existing credentials show as
defaultand are selected when no other profile is active.bashatlas tenants list atlas tenants validate atlas config validateUpdate scripts that call
atlas config set,get, orunsetontenant.id,client.id, orclient.secret, or that rely onatlas config validateto check Graph. Use the table in What breaks.Move per-run credentials into profiles, if hosts back up several tenants by swapping
ATLAS_*variables. Add a profile per tenant, setATLAS_PROFILEor--profilein each job, and remove the Graph variables from the environment.Review scheduled jobs against Changes that affect scheduled jobs. Add
-yto anysavethat writes to a fixed path, handle exit codes2,7,11, and12, and treat4as the credential failure that used to exit1.Check the storage backend with
atlas storage-checkand read theConditional writesrow.Update SDK code for the changes in SDK changes, then run your type checker.
Move replication to the storage provider and remove
atlas replicatejobs, as in Replication moves to the storage provider.Grant Contacts, Calendar, or Teams permissions only if you schedule those workloads.
Confirm the upgrade worked
atlas tenants listshows every tenant you back up, with the right one selected.atlas tenants validate --allandatlas config validateboth pass.- No scheduled job logs the stderr warning about
ATLAS_*variables replacing a profile value. - The next scheduled backup of an existing mailbox, drive, or site runs incrementally from its v6 sync checkpoint.
See also
- Configuration for tenant profiles and selection order.
- CLI reference for
atlas tenantsand--profile. - SDK reference for
createTenant. - Security for what a shared store and a two-identity restore expose.
- Replicas for restoring from and verifying a replica.
- Migrating to v6 when upgrading from v5.

