Skip to content

Work with your first Drive file

View as Markdown

You need an Account identity and access to a Drive in that Account. Reader access lets you browse and download; writer access is needed to add or change files. Files are limited to 16 MiB.

If someone else owns the Drive, ask its owner for writer access before following the upload steps. The owner can grant access through the CLI; the web app does not manage grants. To store your own files, create a Drive first.

Create a Drive if you do not have one

With the Socra CLI installed, add the Drive commands:

sh
socra install drive

For a personal CLI session, run socra account login and select the Account you will use in the Drive web app. If you are already signed in, check socra account status; use socra account switch if it shows another Account. A managed CoAgent uses its own configured credentials.

Create a Drive with a name you will recognize:

sh
socra drive create "Working files"

The signed-in principal becomes its owner. Record the returned id as DRIVE_ID and verify it:

sh
socra drive get DRIVE_ID

Confirm the name, then open the web app using the same Account and identity. A Drive created under a CoAgent’s identity needs an explicit grant before your personal identity can open it.

Upload and check a file

  1. Open Drive and sign in with your Account.
  2. Select a Drive you can access. Open a folder, or create one if you have writer access.
  3. Upload a file. Select Versions to see its version history, then select Download to confirm the current content.
  4. If you need to replace its content, add a new version after checking the current one. Drive rejects a write based on a stale version; reload and review the newer version before trying again.

Deleted files and folders go to trash rather than disappearing permanently; the current release has no permanent-delete action. Restore is subject to the current names in the destination folder, so a name collision must be resolved first. If a parent folder and a child inside it were trashed separately, restore the parent before the child.

Grant access to an existing Drive

Only the Drive owner can manage access. Grants apply to every file and folder in the Drive. Reader access permits browsing and downloading. Writer access also permits content changes, moving entries to trash, and restoring them.

Drive CLI 0.1.1 and later accept the recipient's Account-local Directory ID beginning with user_. Find the recipient in the same Account using Directory:

sh
socra install directory
socra directory user list

Directory returns a page of members. If the recipient is not on that page and a cursor is printed, continue with socra directory user list --after LAST_ID. If a page repeats or you cannot identify the recipient, stop and ask for their verified Account-local Directory ID; do not guess an identifier.

Use the recipient's returned id as DIRECTORY_USER_ID. Do not use a username, email address, personal ID, or Channels member ID. Existing raw Account-user UUIDs remain accepted by the Drive CLI; the API still requires that UUID representation.

Replace DRIVE_ID with the Drive ID and DIRECTORY_USER_ID with the recipient's Directory ID. Run this command as the Drive owner:

sh
socra drive permission grant DRIVE_ID DIRECTORY_USER_ID writer

Use reader instead of writer for download-only access. Repeating the command for the same principal replaces its role. Inspect the grant:

sh
socra drive permission list DRIVE_ID

In Drive CLI 0.1.2 and later, match the grant's principal_user_id to the recipient's Directory id; principal_id is the same recipient's raw Account-user UUID.

Have the recipient run socra drive get DRIVE_ID through their own authenticated session, then open the Drive in the web app. Your owner session cannot verify the recipient’s access.

To remove the grant, use its returned ID as PERMISSION_ID:

sh
socra drive permission revoke PERMISSION_ID

Revocation prevents further authorized access through that grant. It cannot remove files the recipient already downloaded.

Remove a Drive you no longer need

As the owner, run socra drive delete DRIVE_ID to move the Drive and its contents to recoverable trash. Use socra drive restore DRIVE_ID to restore it. The current release has no permanent-delete command.

Read the Drive overview for access and file-lifecycle rules.

See also