--- title: "overlane egress grant" description: "Grant one task a credential for named hosts; the value never reaches the agent" --- > Documentation Index > Fetch the complete documentation index at: https://docs.overlane.app/llms.txt > Use this file to discover all available pages before exploring further. # overlane egress grant {/* Generated by apps/docs/scripts/generate.mjs (CLI pages from the command registry in packages/cli). Do not edit; run `pnpm --filter @overlane/docs gen`. */} Creates a grant bound to this task, a host list and a lifetime (default 15 minutes). The grant names a secret; the egress proxy attaches its value to requests for the granted hosts, and the value is never returned to you, written to a log or put in the workspace. The hosts must already be on the allowlist. A grant for one task, named hosts and at most an hour is an ordinary action. A wider grant (--scope project or team), a longer one, or a wildcard of hosts is class secrets: an agent needs an independent agent's approval (set OVERLANE_APPROVAL to the ID the refusal names), a person does not. ## Usage ```sh overlane egress grant [--task TASK] --host HOST... --secret NAME [--minutes N] [--scope SCOPE] [--header NAME] [--dry-run] ``` ## Flags | Flag | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `--task` | string | no | | The task the grant belongs to (required for a task grant) | | `--host` | string (repeatable) | yes | | A host the credential may be attached for; repeat for more | | `--secret` | string | yes | | The secret's name in the project's secret store, such as NPM_TOKEN | | `--minutes` | string | no | | Lifetime in minutes, 1 to 1440 (default 15) | | `--scope` | one of `task`, `project`, `team` | no | | task (default), project or team; the wider two are class secrets | | `--header` | string | no | | Attach as this header instead of Authorization: Bearer | | `--dry-run` | boolean | no | | Print the requests and file changes this command would make, then stop. Needs no credentials. | ## Examples ```sh overlane egress grant --task task-12 --host api.github.com --secret GITHUB_TOKEN overlane egress grant --task task-12 --host registry.npmjs.org --secret NPM_TOKEN --minutes 30 ``` ## Behavior - Effect: `write` (changes local or hosted state). - Needs credentials: yes. Uses the network: yes. - Supports `--dry-run`: yes. Accepts `--force`: no. - Machine-readable description: `overlane schema egress grant`. ## Result With `--json` (the default when stdout is not a terminal) the command prints this JSON Schema's shape on stdout. ```json { "anyOf": [ { "type": "object", "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$", "description": "tenant identifier" }, "projectId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$", "description": "project identifier" }, "id": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "task", "project", "team" ] }, "taskId": { "type": [ "string", "null" ] }, "hosts": { "type": "array", "items": { "type": "string" } }, "secretName": { "type": "string" }, "attach": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "bearer" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "header" }, "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$" } }, "required": [ "kind", "name" ], "additionalProperties": false } ] }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "uses": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "class": { "type": "string", "enum": [ "grant", "secrets" ] }, "replay": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "tenantId", "projectId", "id", "scope", "taskId", "hosts", "secretName", "attach", "status", "createdBy", "createdAt", "expiresAt", "revokedAt", "uses", "class" ], "additionalProperties": false }, { "type": "object", "properties": { "dryRun": { "type": "boolean", "const": true }, "service": { "type": "string" }, "requests": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "body": {}, "note": { "type": "string" } }, "required": [ "method", "path" ], "additionalProperties": false } }, "commands": { "type": "array", "items": { "type": "string" } }, "writes": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "action": { "type": "string", "enum": [ "write", "append", "delete" ] }, "description": { "type": "string" } }, "required": [ "path", "action", "description" ], "additionalProperties": false } }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "dryRun", "requests", "commands", "writes", "notes" ], "additionalProperties": false } ] } ``` See [exit codes](/cli/#exit-codes) for the status the process returns. Source: https://docs.overlane.app/cli/egress-grant/index.mdx