Skip to content

Quickstart

This 5-minute walkthrough takes you from zero to listing devices and previewing a cross-environment data copy.

1. Configure your environments

Create the configuration file at ~/.config/grace/config.yaml:

default_env: dev

environments:
  dev:
    url: http://localhost:41889
  prod:
    url: https://grace.production.example.com

Tip

You can add as many environments as you need. The default_env is used when you omit the --env flag.

2. Log in

Store credentials for your dev environment:

grace auth login --env dev

You'll be prompted for username and password interactively. Credentials are saved in your OS keyring (or a local file with restricted permissions on headless systems).

Logging in to dev (http://localhost:41889)
Username: admin
Password: ********
OK: Credentials saved for 'dev' (backend: SecretService)

3. Check status

Verify connectivity to all configured environments:

grace auth status

         Authentication Status
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Environment   ┃ URL                     ┃ Backend       ┃ Username ┃ Connectivity ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ dev (active)  │ http://localhost:41889  │ SecretService │ a***n    │ reachable    │
│ prod          │ https://grace.prod...   │ SecretService │ none     │ no creds     │
└───────────────┴─────────────────────────┴───────────────┴──────────┴──────────────┘

4. List devices

grace device list

            Devices (page 1, 42 total)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ ID                                  ┃ Name      ┃ Type     ┃ Device No  ┃ Vendor ID ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ a1b2c3d4-...                        │ rover-01  │ lidar    │ DEV-001    │ ...       │
│ ...                                 │ ...       │ ...      │ ...        │ ...       │
└─────────────────────────────────────┴───────────┴──────────┴────────────┴───────────┘

Add --output json to get raw JSON for scripting:

grace device list --output json

5. Preview a data copy

See what a production-to-dev copy would do — without actually writing anything:

grace data copy \
  --source prod --target dev \
  --entity videos --limit 10 \
  --dry-run

Connecting to source (prod) and target (dev)...
Building copy plan...

        Copy plan: prod → dev
┏━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Entity   ┃ Selected ┃ Dependencies  ┃ Already in target ┃ To create ┃
┡━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ devices  │        0 │             3 │                 1 │         2 │
│ locations│        0 │             2 │                 2 │         0 │
│ vendors  │        0 │             1 │                 0 │         1 │
│ videos   │       10 │             0 │                 2 │         8 │
└──────────┴──────────┴───────────────┴───────────────────┴───────────┘

Dry run — no changes made.

The plan shows that copying 10 videos also requires creating 2 devices and 1 vendor that don't yet exist in dev. Dependencies are resolved automatically.

6. Preview a video transfer

For a deeper transfer that includes annotation runs, segmentations, video steps, and optionally GCS files:

grace data transfer \
  --source prod --target dev \
  --limit 5 \
  --dry-run

Connecting to source (prod) and target (dev)...
Building transfer plan...

      Transfer plan: prod → dev
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Entity                  ┃ Selected ┃ Already in target ┃ To create ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ devices (by device_no)  │        3 │                 2 │         1 │
│ collectors (by name)    │        - │                 - │         0 │
│ locations               │        2 │                 2 │         0 │
│ vendors                 │        1 │                 0 │         1 │
│ videos                  │        5 │                 1 │         4 │
│ annotation_runs         │        8 │                 0 │         8 │
│ segmentations           │       12 │                 0 │        12 │
│ video_steps             │       40 │                 0 │        40 │
└─────────────────────────┴──────────┴───────────────────┴───────────┘

Dry run — no changes made.

Add --copy-files to also copy referenced GCS blobs to the target bucket.

Next steps