Inspect local spaces

Use arc space to inspect local DID Space data: which app fragments exist, what logical tree they hold, and which AFS path a fragment maps to. This is offline DX on a data directory. It is not a substitute for a live session view (/user, /tmp, /space), and it is not a formal cloud deployment.

Verified against ARC CLI 2.0.0-beta.42. Full man-style coverage of every subcommand also lives in arc space. This page focuses on a reproducible local recipe and failure modes.

Preconditions

Item	Value used in the capture below
CLI	`arc` `2.0.0-beta.42` (`arc --version`)
Isolated root	`/tmp/arc-ids-docs-fixture` (any empty directory you own)
Fixture user DID	`z1fixtureIdentityDocs000000000000001`
Fixture app DID	`todo-docs-fixture`
Isolation flags	`--root-path` and `--user-did` on every inspection command

Always pass an isolated --root-path when documenting or experimenting. Default config may point at your real ~/.afs/spaces and list production app fragments.

You may see boot warnings such as AFS_DID_SPACE_SCOPE_SECRET unset when de-identification is off. They do not block local inspection; they mean on-disk directories may use plaintext identifiers.

1. Confirm empty root

arc space list \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001

Actual output:

No app spaces found

list is the whole overview: DIDs, file counts and roots, for whichever --scope you ask for.

2. Seed a sample tree into the instance (system) fragment

sync takes two directories, so first ask path where the fragment lives:

arc space path todo-docs-fixture / \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance

/spaces/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/system

The first segment after /spaces/ is the scope directory, derived from the user DID. With de-identification on it is an HMAC of the DID, not the DID itself — yours will differ from the capture above, which is why the recipe reads it back rather than hard-coding it. Swap /spaces for your --root-path and you have the on-disk destination:

mkdir -p /tmp/arc-ids-sample-fixture/notes
printf '%s\n' 'hello from identity docs evidence' > /tmp/arc-ids-sample-fixture/notes/readme.txt
printf '%s\n' 'secondary' > /tmp/arc-ids-sample-fixture/notes/extra.md

arc space sync \
  --from /tmp/arc-ids-sample-fixture \
  --to /tmp/arc-ids-docs-fixture/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/system

Actual output:

/tmp/arc-ids-sample-fixture → /tmp/arc-ids-docs-fixture/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/system
Base path: /
Mode:      additive

Engine:    manifest — the manifest engine works between any two endpoints
  not changelog: the changelog engine is a device↔cloud engine — it needs exactly one local folder (the device) and one remote host (the cloud); neither folder↔folder nor remote↔remote fits it
  not cursor: the cursor engine mirrors (it deletes destination-only paths); this run is additive, so use --mirror to allow deletions or let the manifest engine handle it

Added:     2
Modified:  0
Deleted:   0
Unchanged: 0

Transferred: 2 files
Verified:    no
Duration:    294ms

sync is additive and never deletes existing files unless you pass --mirror. There is no --scope here: the role prefix (system / user) is the last segment of the path you sync into, so the destination itself says which fragment you meant.

3. List

arc space list \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance

DID                  Files  Last Modified
───                  ─────  ─────────────
todo-docs-fixture        2  —

When you override --root-path / --user-did, human output may show a single section rather than the dual “Instance DID Space” / “User DID Space” headers you see against the default home layout. Always pass --scope instance or --scope user when the distinction matters.

4. Tree and path (instance → system)

arc space tree todo-docs-fixture \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance

todo-docs-fixture:
[d] /notes  (128 B)
    /notes/extra.md  (10 B)
    /notes/readme.txt  (34 B)

arc space path todo-docs-fixture /notes \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance

/spaces/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/system/notes

path prints the logical AFS path for the role fragment. It is not a shell filesystem path and not a session path such as /user/notes — but as step 2 showed, replacing /spaces with your --root-path does give you the directory on disk.

5. User-scope fragment

Same move, one path segment different — user instead of system:

arc space sync \
  --from /tmp/arc-ids-sample-fixture \
  --to /tmp/arc-ids-docs-fixture/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/user/docs

/tmp/arc-ids-sample-fixture → /tmp/arc-ids-docs-fixture/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/user/docs
Base path: /blocklets/todo-docs-fixture/user/docs
Mode:      additive

Engine:    manifest — the manifest engine works between any two endpoints
  not changelog: the changelog engine is a device↔cloud engine — it needs exactly one local folder (the device) and one remote host (the cloud); neither folder↔folder nor remote↔remote fits it
  not cursor: the cursor engine mirrors (it deletes destination-only paths); this run is additive, so use --mirror to allow deletions or let the manifest engine handle it

Added:     2
Modified:  0
Deleted:   0
Unchanged: 0

Transferred: 2 files
Verified:    no
Duration:    337ms

arc space tree todo-docs-fixture \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope user

todo-docs-fixture:
[d] /docs  (96 B)
[d] /docs/notes  (128 B)
    /docs/notes/extra.md  (10 B)
    /docs/notes/readme.txt  (34 B)

arc space path todo-docs-fixture /docs \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope user

/spaces/sws6a445s4sgwlarm6eg32hkoppspbs2/blocklets/todo-docs-fixture/user/docs

Instance scope maps to the system role prefix; user scope maps to the user role prefix. That matches the provider's getInstanceSpace({ role }) contract — and it is why a sync destination ending in /system or /user/docs lands where it does.

6. Delete inside a fragment

arc space rm todo-docs-fixture /notes/extra.md \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance

Deleted todo-docs-fixture [instance] /notes/extra.md

arc space tree todo-docs-fixture \
  --root-path /tmp/arc-ids-docs-fixture \
  --user-did z1fixtureIdentityDocs000000000000001 \
  --scope instance

todo-docs-fixture:
[d] /notes  (96 B)
    /notes/readme.txt  (34 B)

Default --scope for rm is user. Pass --scope instance when deleting from the system fragment.

Use rm rather than deleting the file from the fragment directory by hand: a bare rm -rf leaves a phantom row in the space's index, which only arc space repair --folder <dir> clears.

Failure modes (captured)

Situation	Command	Observed result
Unknown app DID	`arc space tree does-not-exist-app --root-path … --user-did … --scope instance`	`ERROR: App space not found: does-not-exist-app`
Invalid scope on `tree`	`arc space tree todo-docs-fixture … --scope all`	`Invalid values: Argument: scope, Given: "all", Choices: "instance", "user"`
Missing app argument on `path`	`arc space path`	`Not enough non-option arguments: got 0, need at least 1`
Empty root	`arc space list` on a fresh directory	`No app spaces found`

tree and path do not accept --scope all. Use list for the multi-scope overview, then inspect one role at a time.

What local inspection is not

Local `arc space`	Live session / formal deployment
Operates on a chosen root directory	Operates on runtime-mounted session views
Shows `system` / `user` fragments under `/spaces/…/blocklets/…`	Exposes `/user`, `/tmp`, optional `/space` to a caller
Does not authenticate end users for you	Requires verified `CallerInfo` for user overlays
Remote `sync` (an `https://<host>` end) needs server auth	Not re-run on this page; treat as separate environment-specific ops

Do not deploy to DID Space only to inspect data for documentation or local UI work. Run the blocklet locally, and use an isolated --root-path for space CLI experiments.

Provider role prefixes: DID-scoped storage
Session composition: User, temporary, and space views
How to re-run this page on a newer CLI: Evidence and version boundaries
Full subcommand list: arc space