> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/resources/reporters/currents-cmd/currents-session.md). # currents session Capture an agent or browser session as evidence in Currents, attach screenshots, Playwright traces and logs, and share a link, with the currents session commands `currents session` captures a one-off agent or browser session as evidence, such as a bug before and after a fix, or proof that something works. You create a session, attach screenshots, a Playwright trace, videos and other files to it, and share a link that opens the session without a Currents account. A session is not a run. It has no spec files or tests, and it does not appear in run lists or analytics. ## Usage The commands take either key: * The [record key](/guides/record-key.md) your CI already uses to report runs, as `--key` or `CURRENTS_RECORD_KEY`. * An [API key](/dashboard/administration/api-keys.md) with write access, as `--api-key` or `CURRENTS_API_KEY`. With both set, the record key is used. A record key can create, attach to and share sessions; it cannot list, read or delete them. ```bash npm install @currents/cmd --save-dev npx currents session start --project-id --title "Checkout fails on empty cart" --status failed npx currents session attach before.png .playwright-mcp/traces npx currents session share --expires-in-days 7 ``` Outside a project that installs `@currents/cmd` 2.x, use `npx --package @currents/cmd@2 currents` in place of `npx currents`. A session is complete when it is created. There is no command to end it: `attach` adds files at any time, and `share` can run before or after `attach`.
A terminal: currents session start creates a session in a project, currents session attach uploads a folder with a console log, a page snapshot, a screenshot and a Playwright trace, and currents session share prints the session link and its Markdown link
## currents session start `session start` creates the session and saves its ID to `.currents-session/session.json` in the current folder. It also writes `.currents-session/.gitignore`, so git ignores the folder. `attach` and `share` read the saved ID, so run them in the same folder, or pass `--session-id`. A new `session start` in the same folder replaces the saved session, so share a session before you start the next one. To record several sessions at the same time, run each from its own folder, or pass `--session-id` to every `attach` and `share`. The commit, branch and author come from the git repository in the current folder. Outside a repository the session has none. | Option | Environment variable | Description | | ------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------- | | `-k, --key ` | `CURRENTS_RECORD_KEY` | A record key. Required unless `--api-key` is set. | | `--api-key ` | `CURRENTS_API_KEY` | An API key with write access. Used when `--key` is not set. | | `-p, --project-id ` | `CURRENTS_PROJECT_ID` | The project to create the session in. Required. | | `--title ` | | What the session shows. Required. | | `--status ` | | The result of the session: `passed` or `failed`. Default: `passed`. | | `--error ` | | What went wrong, for a failed session. | | `-t, --tag ` | | Tags to add to the session. Comma-separated or repeated. | | `--pr ` | | The pull request the session is about. Default: taken from the CI environment. | | `--json` | | Print the session ID as JSON on stdout, for example `{"sessionId":"..."}`. Other messages go to stderr. | | `--debug` | `CURRENTS_DEBUG` | Print debug logs. Keys are hidden in them. Default: `false`. | The command prints `Session started: `. ## currents session attach `session attach` uploads files and folders to the session. ```bash npx currents session attach ``` * A file is uploaded as it is. * A folder that holds Playwright MCP `trace-*.trace` files is packed into one trace, and nothing else in it is attached. A folder with a `traces/` subfolder that holds them adds the packed trace and the folder's own files. Playwright MCP writes its traces to `.playwright-mcp/traces`, unless it runs with `--output-dir`. * Of any other folder, every file in it and in its subfolders is attached, named by its path inside the folder. A `trace.zip` in a subfolder is attached as a trace. Attach a whole Playwright `test-results` folder this way. Hidden files, links and empty files are skipped with a warning. * A file named `.env` or `.env.*` is refused, and so is a file larger than 1 GiB. The type of each file comes from its name: | File | Type | | -------------------------------------------------------------------------- | ------------ | | `.zip` that holds `trace.trace`, or a folder of Playwright MCP trace files | `trace` | | `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif` | `screenshot` | | `.webm`, `.mp4` | `video` | | Any other file | `attachment` | | Option | Environment variable | Description | | ------------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------- | | `-k, --key ` | `CURRENTS_RECORD_KEY` | A record key. Required unless `--api-key` is set. | | `--api-key ` | `CURRENTS_API_KEY` | An API key with write access. Used when `--key` is not set. | | `--session-id ` | `CURRENTS_SESSION_ID` | The session to attach to, instead of the one saved by `session start`. | | `--type ` | | The type of every file: `trace`, `screenshot`, `video` or `attachment`. Default: taken from the file name. | | `--caption ` | | A short description shown with each file. At most 1,000 characters. | | `--meta ` | | A label for each file. Repeat for more, up to 20. A key holds letters, digits, `_` and `-`. | | `--debug` | `CURRENTS_DEBUG` | Print debug logs. Keys are hidden in them. Default: `false`. | The command prints `Attached ()` for each file that arrived, and `Failed : ` on stderr for each file that did not. If any file failed, it exits with `1`. Attach only the failed files again. A session holds at most 200 files. ## currents session share `session share` creates a public link to the session page and prints it. The second line, `Markdown: `, is the address of the same content as Markdown, for agents. ```bash npx currents session share --expires-in-days 7 ``` The page shows the session as it is when opened, so files attached after `share` appear on it. Each call creates a new link. | Option | Environment variable | Description | | -------------------------- | --------------------- | ------------------------------------------------------------------ | | `-k, --key ` | `CURRENTS_RECORD_KEY` | A record key. Required unless `--api-key` is set. | | `--api-key ` | `CURRENTS_API_KEY` | An API key with write access. Used when `--key` is not set. | | `--session-id ` | `CURRENTS_SESSION_ID` | The session to share, instead of the one saved by `session start`. | | `--expires-in-days ` | | The number of days the link works: `1`, `3` or `7`. Default: `7`. | | `--debug` | `CURRENTS_DEBUG` | Print debug logs. Keys are hidden in them. Default: `false`. | {% hint style="danger" %} Anyone with the link can open the session and its files until the link expires, including the requests, headers and cookies recorded in a trace. Attach only test data and files from test accounts. {% endhint %} If the organization turned public sharing off, `session share` prints the error from the API and exits with `1`. ## Find and delete sessions Sessions and their files follow the [Data Retention](/resources/data-privacy/data-retention.md) periods. A share link stops working when it expires; the session is not deleted with it. * List the sessions of a project with [`GET /v1/projects/{projectId}/sessions`](https://docs.currents.dev/api/resources/sessions), newest first. It filters by branch, tag, pull request, date and text, as the run list does. * Delete a session with [`DELETE /v1/sessions/{sessionId}`](https://docs.currents.dev/api/resources/sessions). It needs an API key with write access. The session stops being readable at once, and Currents removes its files and share links in the background. ```bash npx currents api /v1/projects//sessions -X GET -f limit=10 npx currents api /v1/sessions/ -X DELETE ``` Deleting the organization deletes its sessions too. ## Troubleshooting | Message | Fix | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `No session found. Run "currents session start" first, or pass --session-id` | `session start` did not run in this folder. Run it here, or pass `--session-id`. | | `401` or `403` from `session start` | Neither `CURRENTS_RECORD_KEY` nor `CURRENTS_API_KEY` is set, or the API key has no write access. | | `404` from `session start` | The project ID does not belong to the organization of the key. | To read a session with the REST API, see [Sessions](https://docs.currents.dev/api/resources/sessions). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.currents.dev/resources/reporters/currents-cmd/currents-session.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.