Skip to content

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.

bash
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 check

Who is affected ​

You useWhat to do
The CLI with one tenantNothing required. Existing credentials load as the default profile
Scheduled jobs that branch on the exit code, export with save, or run without a terminalReview 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 GraphSwitch to atlas tenants. See What breaks
One host backing up several tenants by swapping ATLAS_* variablesMove each tenant into a profile
atlas replicate or atlas rehydrateSet up replication at the storage provider. See Replication moves to the storage provider
The SDK with TypeScriptUpdate code for the SDK changes and rerun your type checker
Contacts, Calendar, or TeamsNew and opt-in. Grant their permissions first

What changed ​

Areav6v7
Microsoft Entra credentials (CLI)One set, atlas config set tenant.id, client.id, client.secretNamed tenant profiles, managed with atlas tenants. Existing credentials load as default
atlas configEvery key. validate checks Graph and S3Shared S3 and passphrase keys only. validate checks S3
Selecting a tenantSwap ATLAS_TENANT_ID, ATLAS_CLIENT_ID, ATLAS_CLIENT_SECRET--profile <name>, ATLAS_PROFILE, or atlas tenants use
Cross-tenant restoreManual credential swap--target-profile on the CLI, createTenant and targetTenant in the SDK
WorkloadsOutlook, OneDrive, SharePointAdds Contacts, Calendar, and Teams channel messages
Storage formatv6 pathsUnchanged. Contacts, Calendar, and Teams add the contacts/, calendar/, and teams/ prefixes
Replicationatlas replicate, atlas rehydrate, SDK replication methodsRemoved. The storage provider makes the replica, and Atlas restores from and verifies it
Passphrase rotationatlas keys rewrap re-wraps one tenantatlas keys rewrap re-wraps every profile, see below
Snapshot deletionAny snapshotOnly the newest snapshot of a mailbox, owner, or site. Others exit 11
Concurrent operations on one ownerNot detectedRefused with ATLAS_OWNER_BUSY, exit 12
Rejected Graph credentialsExit 1Exit 4, ATLAS_AUTH_DENIED
Graph Retry-After above 5 minutesFailed after one attemptWaited out, up to 1 hour
Restore fidelityMessages restored unflagged, folder colours not keptRestores 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, and client_secret from v6 load as the default profile. The first atlas tenants write moves them into tenants.default in the store.
  • atlas.config.json. Top-level Graph fields in the file are read as default too. Atlas never rewrites the file.
  • ATLAS_* environment variables. ATLAS_TENANT_ID, ATLAS_CLIENT_ID, and ATLAS_CLIENT_SECRET still 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:

v6v7
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 listatlas tenants list
atlas config unset client.secretatlas 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:

bash
atlas tenants add contoso --tenant-id <tenant-id> --client-id <client-id> --client-secret -
atlas tenants use contoso
atlas tenants remove default

remove 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:

bash
atlas tenants add fabrikam --tenant-id <tenant-id> --client-id <client-id> --client-secret -
atlas --profile fabrikam outlook backup -m user@example.com

Scheduled 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:

bash
atlas --profile contoso outlook restore -s <snapshot-id> --target-profile fabrikam -T user@example.com

The 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:

WorkloadBackup permissionsRestore
ContactsContacts.ReadContacts.ReadWrite
CalendarCalendars.ReadCalendars.ReadWrite
TeamsEight Application permissions, including the protected ChannelMessage.Read.All. See Teams application permissionsExport 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 ​

bash
# 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> --fast

Storage 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 replicate and atlas rehydrate.
  • The 13 SDK methods: replicateSnapshot, replicateMailbox, rehydrateSnapshot, rehydrateMailbox, rehydrateTenant, getReplicationStatus, and getReplicationStatusByOwner on the instance; replicateSnapshot, replicateAll, rehydrateSnapshot, and rehydrateOwner on atlas.onedrive; replicateSnapshot, replicateAll, rehydrateSnapshot, and rehydrateSite on atlas.sharepoint.
  • createStorageTarget, StorageTarget, StorageTargetConfig, and the target field of storage request events.
  • The --target-* options of atlas stats storage and the target option of getStorageUsage, which no v6 release shipped. Measure a replica by pointing the S3 endpoint at it.
  • The result and option types OneDriveSdkReplicationResult, SharePointSdkReplicationResult, and RehydrationWorkload.

What to do ​

  1. Set up provider replication, or a scheduled rclone copy or mc mirror to another provider. See Replica setup.
  2. Remove the atlas replicate cron jobs and systemd timers.
  3. To restore or verify from the replica, point ATLAS_S3_ENDPOINT and the keys at it. See Replicas.
  4. 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's s3Bucket. 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:

CodeWhat v7 adds
1A confirmation prompt that gets no answer, and ATLAS_WRITE_REFUSED. No longer covers rejected Graph credentials, which move to 4
2A 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
3A 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
4A 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
7A --folder, --file-filter, or --message selection that matched nothing at all
9ATLAS_FORMAT_UNSUPPORTED, and a command that skipped a damaged snapshot manifest or version index and named it
11New: ATLAS_SNAPSHOT_NOT_NEWEST
12New: 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 ​

Situationv6v7
save to an output file that existsOverwrote itAsks Overwrite? [Y/n]. Pass -y in a job that writes to a fixed path
A confirmation prompt with no terminal attachedDepended on the commandExits 1 and changes nothing. Pass -y in scheduled jobs
A selector that matches nothingRan and reported successFails with exit 7, or 2 when only some values matched
--message together with -m on atlas outlook restore or saveActed on the whole mailboxRefused. Name the snapshot with -s
delete -s on the newest snapshotLeft the sync checkpoint in placeRemoves it too, so the next backup reads the mailbox, drive, or site in full
A tenant ID that cannot name an S3 bucketFailed at the storage providerRefused with exit 6. Tenant IDs are stored in lowercase
A second Ctrl+CWaited for the run to wind downExits at once with status 130 and no final report
Microsoft Graph sends Retry-After above 5 minutesFailed the call after one attemptWaits 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 tenantRan alongside itRefused with exit 12, and the other way round
Commands that only read a backupOpened the tenant for writingOpen 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:

bash
atlas storage-check

A 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 ​

Itemv6v7
Outlook follow-up flag and pinRestored unflagged and unpinnedRecorded at backup and restored. Messages backed up by v6 still restore unflagged and unpinned
OneDrive and SharePoint folder coloursNot capturedCaptured on folder entries and shown by list-permissions and restore output. Not reapplied on restore
OneDrive and SharePoint sharingNot capturedCaptured, shown by list-permissions, and restored with --restore-permissions
Outlook folder names on restore and saveRead from the source mailbox, so a departed user's mailbox or a cross-tenant restore failed with 404Read 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 ​

CommandPurpose
atlas tenants add, list, use, remove, validateManage tenant profiles
--profile, --target-profileSelect the tenant for a run, and the destination tenant of a restore
atlas contacts, atlas calendar, atlas teamsThe 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-wrappersDelete 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-permissionsShow who had access to which file or folder at a snapshot
--restore-permissions on atlas onedrive restore and atlas sharepoint restoreReapply 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.

ChangeUpdate your code
AtlasInstance gains contacts, calendar, teams, and keysAdd 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 removedRemove the calls and imports. See What is removed
StorageRequestEvent loses targetEvery 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 listSnapshotSummariesAdd them to hand-written mocks of OutlookApi, OneDriveApi, SharePointApi, ContactsApi, or CalendarApi. See Snapshot summaries
Six new AtlasErrorCode valuesAdd cases to an exhaustive switch over err.code. See the table below
MissingGraphPermissionsError is an AuthError, and exportedinstanceof AuthError now matches a missing drive grant. See below
SharePoint sites gain kindlistSites() 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 conditionalWritesAlways present. Add it to a hand-written StorageCheckResult mock
Restore options gain targetTenantA wrapper that copies restore options field by field drops it until updated
createTenant, AtlasTenant, AtlasTenantConfigNew. See Cross-tenant restore
teamsPacingShare on AtlasInstanceConfigNew, optional. Set 1 / n when n processes back up teams of one tenant
s3Bucket on AtlasInstanceConfigNew, optional. Names a bucket other than atlas-{tenantId}, such as an AWS S3 or B2 replica. See Bucket override

New error codes ​

CodeError classRaised whenCLI exit
ATLAS_FORMAT_UNSUPPORTEDUnsupportedFormatVersionError, not exported: match on codeStored data was written by a newer Atlas format version. It is intact: upgrade Atlas9
ATLAS_WRITE_REFUSEDRefusedWriteErrorA backup built a snapshot, index, or sync checkpoint that fails Atlas's own read checks. Nothing is stored1
ATLAS_SNAPSHOT_NOT_NEWESTSnapshotNotNewestErrordeleteSnapshot or delete -s targets a snapshot that is not the newest of its mailbox, owner, or site11
ATLAS_OWNER_BUSYOwnerBusyErrorAnother operation already runs on the same mailbox, drive owner, site, or team12
ATLAS_GRAPH_UNAVAILABLEGraphUnavailableErrorMicrosoft Graph kept answering 500, 502, 503, or 504, or kept failing on the network, through all 12 retries3
ATLAS_ACCESS_REFUSEDGraphAccessRefusedErrorMicrosoft Graph refuses a OneDrive or SharePoint site, drive, or owner with a 403 that is not a missing tenant grant4

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 StoredObjectConflictError or a StorageError naming the object. Both carry ATLAS_STORAGE_FAILURE. The CLI exits 1 for all three. See Refused and unconfirmed metadata writes.
  • Snapshot deletion. outlook.deleteSnapshot, onedrive.deleteSnapshot, and sharepoint.deleteSnapshot, and their delete -s commands, 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 purgeTenantData and 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 with OwnerBusyError. See Concurrent operations.
  • Graph outages. A persistent Graph failure used to reject with the raw Graph error, often with an empty message and no code an AtlasError check could see. GraphUnavailableError carries that error as cause. Treat it as transient. The CLI exits 3 as before. See Graph failures.
  • Refused access. A OneDrive or SharePoint 403 during listing used to reject with MissingGraphPermissionsError, then a plain Error with no code, whatever the cause. A refusal that Atlas does not attribute to a missing tenant grant, such as a SharePoint Embedded container, now rejects with GraphAccessRefusedError. Retrying returns the same answer: a container is unsupported, and another site may need a per-site grant. It is not an AuthError.
  • Rejected credentials. A Graph token request that Microsoft Entra ID refuses used to reject with a GraphError whose statusCode was -1. It now rejects with an AuthError, ATLAS_AUTH_DENIED, carrying Entra's answer as cause. A token request that gets no answer or a transient one rejects with GraphUnavailableError. See Graph failures.
  • Missing permissions. MissingGraphPermissionsError carries ATLAS_AUTH_DENIED and the fields permissions, status_code, and graph_code. Its message changed: it names the HTTP status and Graph code, and for SharePoint names Sites.Read.All or a Sites.Selected grant on the site.
  • Storage check probe. checkStorage() now writes and removes one probe object under _meta/storage-check/, and reports not_probed when 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.
  1. Upgrade @wisecom/atlas-cli or @wisecom/atlas-sdk to v7.

  2. Check the credentials. Existing credentials show as default and are selected when no other profile is active.

    bash
    atlas tenants list
    atlas tenants validate
    atlas config validate
  3. Update scripts that call atlas config set, get, or unset on tenant.id, client.id, or client.secret, or that rely on atlas config validate to check Graph. Use the table in What breaks.

  4. Move per-run credentials into profiles, if hosts back up several tenants by swapping ATLAS_* variables. Add a profile per tenant, set ATLAS_PROFILE or --profile in each job, and remove the Graph variables from the environment.

  5. Review scheduled jobs against Changes that affect scheduled jobs. Add -y to any save that writes to a fixed path, handle exit codes 2, 7, 11, and 12, and treat 4 as the credential failure that used to exit 1.

  6. Check the storage backend with atlas storage-check and read the Conditional writes row.

  7. Update SDK code for the changes in SDK changes, then run your type checker.

  8. Move replication to the storage provider and remove atlas replicate jobs, as in Replication moves to the storage provider.

  9. Grant Contacts, Calendar, or Teams permissions only if you schedule those workloads.

Confirm the upgrade worked ​

  • atlas tenants list shows every tenant you back up, with the right one selected.
  • atlas tenants validate --all and atlas config validate both 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 ​