Skip to content

Artifact Access Management with Apheris CLI🔗

This guide shows you how to use the Apheris CLI to manage access to your artifacts, allowing you to share computational outputs with specific users or organizations.

Prerequisites🔗

  • Apheris CLI installed and configured
  • Authenticated with apheris login (Auth0)
  • Artifacts created by your organization (generated during computations)

Permissions

Only artifact creators and organization admins can manage access. See Who Can Share Artifacts? for details.

Listing Your Shareable Artifacts🔗

To see all artifacts your organization can share:

apheris artifacts list

Example output:

+---+----------------------------------------+---------------------------+------------+------------------+-------------------------+
|  idx  | artifact_id                            | name                      | type       | createdBy        | createdAt               |
+---+----------------------------------------+---------------------------+------------+------------------+-------------------------+
| 0 | c0fd87ef-20ee-430f-ab33-3369bac2cf97   | model-checkpoint-epoch-10 | checkpoint | jane@example.com | 2024-01-15T10:30:00Z    |
| 1 | d1a2b3c4-5e6f-7890-a1b2-c3d4e5f6a7b8   | training-metrics          | metric     | john@example.com | 2024-01-14T15:45:00Z    |
| 2 | a1b2c3d4-e5f6-7890-1234-567890abcdef   | final-model-results       | result     | jane@example.com | 2024-01-13T09:00:00Z    |
+---+----------------------------------------+---------------------------+------------+------------------+-------------------------+

Filter by Artifact Type🔗

To list only specific types of artifacts:

# List only checkpoints
apheris artifacts list --type checkpoint

# List only metrics
apheris artifacts list --type metric

# List only logs
apheris artifacts list --type log

# List only results
apheris artifacts list --type result

Limit Results🔗

Control the number of artifacts returned:

# Return 50 artifacts (default is 20)
apheris artifacts list --page-size 50

# Return only 10 artifacts
apheris artifacts list -s 10

Granting Access to Artifacts🔗

You can grant access to an artifact by email or organization ID. Only one recipient can be specified per grant.

Grant Access by Email🔗

Grant access to a specific user by their email address:

apheris artifacts grant \
  --artifact-id c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  --email collaborator@partner.com

Shorthand:

apheris artifacts grant \
  -i c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  -e collaborator@partner.com

Success output:

Access granted to collaborator@partner.com. Access grant ID: f3g4h5i6-j7k8-9012-l3m4-n5o6p7q8r9s0

Grant Access by Organization🔗

Grant access to all users in a specific organization:

apheris artifacts grant \
  --artifact-id c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  --org-id org_abc123xyz

Shorthand:

apheris artifacts grant \
  -i c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  -o org_abc123xyz

To find organization IDs:

apheris orgs list

Common Scenarios🔗

Share a model checkpoint with a collaborator🔗

# List your checkpoints
apheris artifacts list --type checkpoint

# Grant access to collaborator
apheris artifacts grant \
  -i c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  -e data.scientist@partner-org.com

Share metrics with your partner organization🔗

# List your metrics
apheris artifacts list --type metric

# Get partner organization ID
apheris orgs list

# Grant org-wide access
apheris artifacts grant \
  -i d1a2b3c4-5e6f-7890-a1b2-c3d4e5f6a7b8 \
  -o org_partner123

Viewing Access Grants🔗

To see who has access to a specific artifact:

apheris artifacts list --artifact-id c0fd87ef-20ee-430f-ab33-3369bac2cf97

Shorthand:

apheris artifacts list -i c0fd87ef-20ee-430f-ab33-3369bac2cf97

Example output:

+---+----------------------------------------+----------------------------+----------------+-------------------------+
|  idx  | access_id                              | recipientEmail             | recipientOrgID | createdAt               |
+---+----------------------------------------+----------------------------+----------------+-------------------------+
| 0 | f3g4h5i6-j7k8-9012-l3m4-n5o6p7q8r9s0   | collaborator@partner.com   | None           | 2024-01-15T11:00:00Z    |
| 1 | a1b2c3d4-e5f6-7890-1234-567890abcdef   | None                       | org_partner123 | 2024-01-15T12:30:00Z    |
+---+----------------------------------------+----------------------------+----------------+-------------------------+

Revoking Access🔗

To revoke access, you need both the artifact ID and the access grant ID:

apheris artifacts revoke \
  --artifact-id c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  --access-id f3g4h5i6-j7k8-9012-l3m4-n5o6p7q8r9s0

Shorthand:

apheris artifacts revoke \
  -i c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  -a f3g4h5i6-j7k8-9012-l3m4-n5o6p7q8r9s0

Revoke Workflow🔗

  1. List access grants for an artifact:

    apheris artifacts list -i c0fd87ef-20ee-430f-ab33-3369bac2cf97

  2. Copy the access_id you want to revoke

  3. Revoke the access:

    apheris artifacts revoke \
  -i c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  -a f3g4h5i6-j7k8-9012-l3m4-n5o6p7q8r9s0

Error Handling🔗

Common Errors🔗

Artifact not found:

Artifact not found.
  • Verify the artifact ID is correct
  • Ensure the artifact belongs to your organization

Duplicate grant:

An access grant for this recipient already exists.
  • The user or organization already has access
  • Check existing grants with apheris artifacts list -i <artifact-id>

Authorization failed:

You are not authorized. Please log in or check your permissions.

Invalid parameters:

Specify exactly one of --email or --org-id.
  • You must provide either --email or --org-id, but not both
  • Use --email for individual users or --org-id for organizations

Best Practices🔗

  1. Use organization grants for teams: When sharing with a partner organization, use --org-id to grant access to all their users

  2. Use email grants for individuals: When collaborating with specific people, use --email for granular control

  3. Regularly audit access: Periodically review who has access to your artifacts:

    apheris artifacts list -i <artifact-id>

  4. Revoke when no longer needed: Clean up access grants when collaborations end

  5. Document sharing decisions: Keep records of why access was granted, especially for compliance