CLI reference

atfg is the installed CLI for hosted ATFGraph: sign in, manage team access, create nodes, build, deploy and run them. This reference covers every command and subcommand in the hosted CLI, including release retries, rollback, member management, secrets, sharing and external tokens.

atfg --version
atfg --help
atfg deploy --help
atfg team set-role --help

Use the help from your installed version if an option differs. For installation or upgrades, see Installation. The framework's server-management CLI is a separate tool: legacy examples containing atfg install, atfg serve or atfg package do not describe commands in this hosted CLI. Ask AI-LAB for that workflow.

Global options and context

Option	Meaning
`--team <team>`	Team context; overrides `ATFG_TEAM` and the saved team.
`--env dev` or `--env prod`	Environment; overrides `ATFG_ENV` and the saved environment. Defaults to `dev`.
`--json`	Request machine-readable output. Some mutation acknowledgements still print text; check the command's output before scripting it. Log streams produce one JSON object per line.
`--help`, `-h`	Show help for a command or subcommand.
`--version`, `-V`	Show the CLI version.

Use explicit team and environment flags in scripts:

atfg --team sandbox --env dev status hello-world --json

For team and environment selection, flags take precedence over environment variables, then saved configuration. Commands that resolve team membership may select your only team; setting a default avoids ambiguity across commands.

Command	Options and behavior
`atfg login`	Company sign-in in a browser. `--no-browser` prints the link. `--listen-address <IP>` selects the callback bind address; default `127.0.0.1`.
`atfg logout`	End the session everywhere that session is used, including Console sharing it.
`atfg whoami`	Show the signed-in identity, teams, roles and pending-approval count.
`atfg doctor`	Check installation, session and service. `--local` checks local build tools without network access or sign-in.

For a remote shell, use atfg login --no-browser and open the printed link on the computer with the callback connection. A VM/container can require forwarding the callback port; use a loopback-only host port if binding the guest listener to 0.0.0.0. A guest session does not sign in the Mac Console. See Sign in.

Configuration

Command	Behavior
`atfg config show`	Display API address, default team and environment. Text output also shows the config file path.
`atfg config set <key> <value>`	Set `team`, `env` (`dev` or `prod`), or `api`.
`atfg config unset <key>`	Remove the saved `team`, `env` or `api` value.

atfg config set team sandbox
atfg config set env dev
atfg config show

Settings normally live in ~/.atfgraph/config.toml. The installer provides the hosted service address. Change api only when AI-LAB provides another endpoint; ATFG_API overrides the saved API setting. Sign-in credentials are stored separately from this configuration.

Teams and membership

Command	Behavior
`atfg team ls`	List teams and your role.
`atfg team show <team>`	Show team counts and members.
`atfg team create <name> [--reason <text>]`	Request a new team; the requester becomes its first owner after approval.
`atfg team join <team>`	Request developer membership from the team's owners.
`atfg team set-role <team> <email> <role>`	Owner operation: set `viewer`, `developer` or `owner`.
`atfg team remove <team> <email>`	Remove a member as an owner, or remove yourself to leave the team.

Creation and membership requests can return exit code 3: pending approval, not a failed installation. See Teams & approvals.

Projects and node source

Command	Options and behavior
`atfg project ls`	List projects in the selected team.
`atfg project create <name> [--title <text>]`	Create a project with an optional display title.
`atfg new <name> --project <project>`	Register a node and scaffold its source. Names use lowercase letters and hyphens. `--description <text>` describes it; `--dir <path>` chooses the directory (default: node name).
`atfg ls`	List visible nodes.
`atfg pull <node> [--dir <path>] [--version <version>]`	Fetch the node's source; defaults to the newest version.
`atfg status [node]`	Show versions, health and recent deployments. Without a node, use the node in the current directory, or list nodes if outside one.

Keep node directories as siblings. A team/project name describes ownership, not a requirement to nest a node inside another node.

Build and deployment

Command	Options and behavior
`atfg build [dir]`	Local manifest, pinned dependency, secret-file, test and lint checks. Directory defaults to `.`. Uses the installer-managed Python environment.
`atfg deploy [dir]`	Build/upload a release and follow its deployment. Directory defaults to `.`; environment defaults to `dev`. `--notes <text>` records a change note. `--no-wait` returns when accepted.
`atfg deploy --release <release-id>`	Retry an already uploaded release without building or uploading again. Supports `--no-wait`. Cannot combine with a directory, `--notes` or `--rollback`.
`atfg deploy [dir] --rollback`	Roll back the node identified by the directory. Supports `--no-wait`.
`atfg rollback <node> [--no-wait]`	Roll back the named node to its previously deployed version.

Production changes and other controlled changes can require approval. Acceptance with --no-wait is not proof of a healthy rollout: inspect atfg status <node> afterward.

atfg build
atfg --env dev deploy --notes "Greeting capability"
atfg --env dev status hello-world --json

If a rollout failed before the node started, keep the returned release ID. Recover the cause, then run atfg --env dev deploy --release <release-id>; do not bump the version merely to retry. See Test, build & deploy.

Runs and logs

Command	Options and behavior
`atfg run <node>.<capability> [json]`	Submit a capability call and watch its result. Input defaults to `{}`. `--session <id>` continues a session; `--idempotency-key <key>` identifies a repeated request; `--no-wait` returns the run ID without waiting.
`atfg logs <node>`	Read node output. `--since <window>` accepts e.g. `30m`, `2h`, `1d`; `--errors` filters errors; `--follow` follows new output.

atfg --env dev run hello-world.greet '{"name":"Ada"}'
atfg --env dev logs hello-world --since 30m

Match the returned run ID in Desktop Console, under the same team and environment. In hosted usage, atfg run invokes a deployed capability; it does not start a local worker process.

Node secrets

Command	Behavior
`atfg secret set <node> <NAME>`	Read the value from a hidden prompt or stdin. Values cannot be read back. Production updates can require approval.
`atfg secret ls <node>`	List secret names and metadata, not values.
`atfg secret rm <node> <NAME>`	Remove a secret in the selected environment.

Prefer the interactive hidden prompt for manual use. Do not put secret values in command arguments, shell history, source files or support reports.

Command	Behavior
`atfg share request <team>.<node>`	Ask the owning team to let your team's nodes call their node.
`atfg share ls`	List shares granted to your team and shares granted by it.
`atfg share revoke <share-id>`	Withdraw a share your team granted.

Sharing grants access; it does not copy or deploy the other team's source.

External tokens

Command	Options and behavior
`atfg token create --name <name> --invoke <target>`	Issue a token for an external system. Repeat `--invoke` for multiple nodes or `node.capability` targets. `--expires <days>` defaults to 90, maximum 90. Production issuance can require approval.
`atfg token ls`	List tokens and metadata.
`atfg token revoke <token-id>`	Revoke a token.

An issued token is shown once. Store it securely. These are external invocation credentials, distinct from your company sign-in session and GitHub package-download credentials.

Approvals and audit

Command	Options and behavior
`atfg approvals [--all]`	List requests you can decide; `--all` includes other requests visible to you.
`atfg approve <id> [--note <text>]`	Approve a request as an eligible approver. For production secret requests, `--secret-from-stdin` supplies the value through stdin.
`atfg reject <id> --reason <text>`	Reject with a reason.
`atfg audit [--action <action>]`	Inspect the audit trail; e.g. `--action deploy`. Owners see their team; platform access follows service policy.

The service checks your role and whether you are eligible to act on the request. Follow the named approver instead of assuming a request can be self-approved. These commands govern platform requests; SDK approval pauses inside a node are covered by Python SDK.

Exit codes and automation

Code	Meaning	Next action
`0`	Command completed, or an asynchronous request was accepted.	With `--no-wait`, inspect the deployment/run result separately.
`1`	Local check, operation or run failed.	Read the specific error or failed check.
`2`	Invalid command syntax or arguments.	Read that command's `--help`.
`3`	A request is awaiting approval.	Keep the approval ID; do not submit duplicates.
`4`	Not signed in or permission denied.	Check `whoami`, team and role.
`5`	Service unavailable, internal service error or deadline exceeded.	Capture the ID and time; contact AI-LAB if it persists.

Prefer full IDs from structured output when supported. Capture stderr as well as stdout for errors. Use Get support for a diagnostic report that excludes credentials.