Release Tracking

Create a new release. If no version is provided, auto-detects from package.json version field, then falls back to the latest git tag. This command is idempotent: re-running with the same version silently succeeds.

Flags

Examples

# Create a release with explicit version
tracekit releases new v1.2.3

# Auto-detect version from package.json or git tag
tracekit releases new

# Create with metadata
tracekit releases new v1.2.3 --commit abc123 --url https://github.com/org/repo/releases/v1.2.3 --author "Dev Name"

# JSON output for CI
tracekit releases new v1.2.3 --json

Mark a release as finalized. This signals that the release is complete and fully deployed. If no version is provided, auto-detects from package.json or the latest git tag.

Flags

Examples

# Finalize with explicit version
tracekit releases finalize v1.2.3

# Auto-detect version
tracekit releases finalize

# JSON output
tracekit releases finalize --json

Combined shortcut that creates a release, registers a deploy, and finalizes the release in one command. Each step is idempotent: if the release already exists, it continues to the deploy step. If no version is provided, auto-detects from package.json or the latest git tag.

Flags

Examples

# Deploy to production (auto-detect version)
tracekit releases deploy --env production

# Deploy a specific version to staging
tracekit releases deploy v1.2.3 --env staging

# Deploy with deployer metadata
tracekit releases deploy --env production --deployer deploy-bot

# Full CI/CD usage with JSON output
tracekit releases deploy v1.2.3 --env production --commit abc123 --json

List all releases with version, source, creation date, and finalization status. Supports pagination for large release histories.

Flags

Examples

# List releases
tracekit releases list

# Paginated output
tracekit releases list --page 2 --page-size 10

# JSON output
tracekit releases list --json

Example output

Releases (page 1, 3 total):

  VERSION              SOURCE          CREATED              FINALIZED
  -------              ------          -------              ---------
  v1.2.3               cli             2025-03-15T10:30:00  2025-03-15T10:35:00
  v1.2.2               cli             2025-03-10T14:20:00  2025-03-10T14:22:00
  v1.2.1               auto-detected   2025-03-05T09:00:00  -

Environments: production, staging

Create a new release. Idempotent: creating the same version again returns the existing release.

Request body

{
  "version": "v1.2.3",
  "commit_sha": "abc1234",
  "url": "https://github.com/org/repo/releases/v1.2.3",
  "author": "Dev Name"
}

Response 201 Created

{
  "id": "rel_abc123",
  "version": "v1.2.3",
  "commit_sha": "abc1234",
  "url": "https://github.com/org/repo/releases/v1.2.3",
  "author": "Dev Name",
  "source": "cli",
  "created_at": "2025-03-15T10:30:00Z",
  "finalized_at": null
}

List all releases with pagination.

Query parameters

Response 200 OK

{
  "releases": [
    {
      "id": "rel_abc123",
      "version": "v1.2.3",
      "source": "cli",
      "created_at": "2025-03-15T10:30:00Z",
      "finalized_at": "2025-03-15T10:35:00Z"
    }
  ],
  "environments": ["production", "staging"],
  "total": 1,
  "page": 1
}

Get details for a specific release, including its deploy history.

Path parameters

Response 200 OK

{
  "release": {
    "id": "rel_abc123",
    "version": "v1.2.3",
    "commit_sha": "abc1234",
    "url": "https://github.com/org/repo/releases/v1.2.3",
    "author": "Dev Name",
    "source": "cli",
    "created_at": "2025-03-15T10:30:00Z",
    "finalized_at": "2025-03-15T10:35:00Z"
  },
  "deploys": [
    {
      "id": "dep_xyz789",
      "environment": "production",
      "deployer": "deploy-bot",
      "deployed_at": "2025-03-15T10:32:00Z"
    }
  ]
}

Finalize a release. Sets finalized_at to the current timestamp.

Path parameters

Response 200 OK

{
  "id": "rel_abc123",
  "version": "v1.2.3",
  "source": "cli",
  "created_at": "2025-03-15T10:30:00Z",
  "finalized_at": "2025-03-15T10:35:00Z"
}

Register a deployment for an existing release.

Path parameters

Request body

{
  "environment": "production",
  "deployer": "deploy-bot"
}

Response 201 Created

{
  "id": "dep_xyz789",
  "environment": "production",
  "deployer": "deploy-bot",
  "deployed_at": "2025-03-15T10:32:00Z"
}

Get health metrics for a release, including crash-free rate, issue counts, and trend data.

Path parameters

Response 200 OK

{
  "crash_free_rate": 99.2,
  "total_sessions": 15420,
  "crashed_sessions": 123,
  "crash_free_history": [
    { "date": "2025-03-15", "rate": 99.5 },
    { "date": "2025-03-16", "rate": 99.1 },
    { "date": "2025-03-17", "rate": 99.2 }
  ],
  "new_issue_count": 3,
  "regressed_issue_count": 1
}

If you see not authenticated. Run 'tracekit login' first, your CLI session has expired or was never created.

# Re-authenticate
tracekit login

# Verify authentication
tracekit status

The CLI tries to detect the version from package.json in the current directory first, then falls back to the latest git tag. If neither is found, pass the version explicitly.

# Check that package.json exists and has a "version" field
cat package.json | grep version

# Or check for git tags
git tag --list

# Provide version explicitly as a fallback
tracekit releases new v1.2.3

If releases created via the CLI are not showing in the dashboard, verify that your API key has the correct scope and belongs to the same organization.

# Verify your releases exist via CLI
tracekit releases list --json

# Check that the API key matches your organization
tracekit status